mcpserver.so LogoMCPFly
Submit
1scan logo

1scan

by huahuayu

Blockchain & CryptoAPI GatewayBlockchain ExplorerEtherscanEthereumBSCArbitrumPolygon

1scan is a unified API gateway for integrating multiple etherscan-like blockchain explorer APIs with Model Context Protocol (MCP) support for AI assistants. It provides a single endpoint to access blockchain data and allows AI models to directly query blockchain information.

View on GitHub

Last updated: N/A

1scan - Blockchain Explorer API Gateway & MCP Server

A unified API gateway for integrating multiple etherscan-like blockchain explorer APIs with Model Context Protocol (MCP) support for AI assistants.

Overview

1scan provides two main components:

  1. API Gateway: A unified endpoint for accessing multiple blockchain explorer APIs
  2. MCP Server: Allows AI models (like Claude in Cursor IDE) to directly query blockchain data

Supported Blockchain Networks

Apply for your own API key from the corresponding blockchain explorer

| Network Name | Chain ID | Explorer Link | Explorer API Endpoint | | ------------------- | -------- | ------------------------------- | ------------------------------------ | | Ethereum | 1 | https://etherscan.io | api.etherscan.io | | Binance Smart Chain | 56 | https://bscscan.com | api.bscscan.com | | Arbitrum One | 42161 | https://arbiscan.io | api.arbiscan.io | | Polygon | 137 | https://polygonscan.com | api.polygonscan.com | | Optimism | 10 | https://optimistic.etherscan.io | api-optimistic.etherscan.io | | Avalanche C-Chain | 43114 | https://snowtrace.io | api.snowtrace.io | | Base | 8453 | https://basescan.org | api.basescan.org | | zkSync Era | 324 | https://explorer.zksync.io | block-explorer-api.mainnet.zksync.io | | Gnosis | 100 | https://gnosisscan.io | api.gnosisscan.io | | Fantom | 250 | https://ftmscan.com | api.ftmscan.com | | Mantle | 5000 | https://mantlescan.info | api.mantlescan.info | | Cronos | 25 | https://cronoscan.com | api.cronoscan.com | | Polygon ZkEVM | 1101 | https://zkevm.polygonscan.com | api-zkevm.polygonscan.com | | Linea | 59144 | https://lineascan.build | api.lineascan.build | | Moonbeam | 1284 | https://moonscan.io | api.moonscan.io | | Celo | 42220 | https://celoscan.io | api.celoscan.io | | Scroll | 534352 | https://scrollscan.com | api.scrollscan.com | | OpBNB | 204 | https://opbnbscan.com | api.opbnbscan.com | | Moonriver | 1285 | https://moonriver.moonscan.io | api-moonriver.moonscan.io | | Arbitrum Nova | 42170 | https://nova.arbiscan.io | api-nova.arbiscan.io | | Blast | 81457 | https://blastscan.io | api.blastscan.io | | Fraxtal | 252 | https://fraxscan.com | api.fraxscan.com | | Wemix | 1111 | https://wemixscan.com | api.wemixscan.com | | Xai | 660279 | https://xaiscan.io | api.xaiscan.io | | World Chain | 480 | https://worldscan.org | api.worldscan.org | | Ape | 33139 | https://apescan.io/ | api.apescan.io | | Kroma | 255 | https://kromascan.com | api.kromascan.com | | Taiko | 167000 | https://taikoscan.io | api.taikoscan.io | | Bittorrent | 199 | https://bttcscan.com | api.bttcscan.com | | Xdc | 50 | https://xdcscan.io | api.xdcscan.io |

Features

  • 🔄 Unified API endpoint for multiple blockchain explorers
  • ⚖️ API load balancing
  • 🔑 API rate limit management
  • 🎯 Custom API key support via URL parameters
  • 🤖 MCP server for AI assistants to query blockchain data

Installation

From Go

go install github.com/huahuayu/1scan@latest

From Source

# Clone the repository
git clone https://github.com/huahuayu/1scan.git
cd 1scan

# Build both 1scan API server and MCP server
make build

Quick Start

1. Create Configuration File

Create a config.json file with your API keys:

{
  "1": {
    "endpoint": "api.etherscan.io",
    "keys": {
      "YOUR_ETHERSCAN_API_KEY_1": 5,
      "YOUR_ETHERSCAN_API_KEY_2": 10
    }
  },
  "56": {
    "endpoint": "api.bscscan.com",
    "keys": {
      "YOUR_BSCSCAN_API_KEY": 5
    }
  }
}

Each chain entry contains:

  • chainID: The blockchain network ID
  • endpoint: The API endpoint for the blockchain explorer
  • keys: Map of API keys and their rate limits (requests per second)

2. Run the API Server

# Run with default settings
1scan -config /path/to/config.json

# Or using make
make run-1scan

3. Run the MCP Server

# Run with default settings
1scanmcp -config /path/to/config.json # default serve at port 3000

# Or using make
make run-1scanmcp

# With custom settings
1scanmcp -config /path/to/config.json -port 3000 -path /mcp

Integrating with Cursor IDE

To use 1scan MCP in Cursor IDE:

  1. Start both the API server and MCP server

    # Terminal 1
make run-1scan

# Terminal 2
make run-1scanmcp

  2. In Cursor IDE, go to Settings → AI → MCP Servers

  3. Add a new MCP server with the URL:

{
  "mcpServers": {
    "1scan": {
      "url": "http://localhost:3000/mcp/sse"
    }
  }
}

  1. Restart Cursor IDE if necessary

  2. Now you can use blockchain data in your AI conversations:

    Can you check the balance of address 0x742d35Cc6634C0532925a3b844Bc454e4438f44e on Ethereum?

MCP Server Configuration

When running the MCP server, you can customize it with these parameters:

  • -port: Port to run the MCP server on (default: "3000")
  • -path: Path for the MCP server endpoint (default: "/mcp")
  • -config: Path to configuration file (default: "config.json")
  • -transport: Transport type (sse or stdio) (default: "sse")

Example:

1scanmcp -port 3000 -config /path/to/config.json

Available MCP Tools

The MCP server exposes these tools to AI models:

  • getAccountBalance - Get the balance of an account on a specific blockchain
  • getTokenBalance - Get the token balance of an account on a specific blockchain
  • getTransactionByHash - Get transaction details by hash
  • getBlockByNumber - Get block information by block number
  • getContractABI - Get the ABI for a verified contract
  • getContractSourceCode - Get the source code of a verified contract
  • getTokenInfo - Get information about an ERC20 token
  • getGasPrice - Get current gas price on a specific blockchain
  • getLogs - Get event logs matching specified parameters
  • getTransaction - Get details of a transaction by its hash
  • getTransactionCount - Get the number of transactions sent from an address
  • getTransactionReceipt - Get transaction receipt by transaction hash
  • getBlockTransactionCountByNumber - Get the number of transactions in a block
  • getBlockTransactionCountByHash - Get the number of transactions in a block by block hash
  • getBlockByHash - Get information about a block by its hash
  • getNormalTransactions - Get normal transactions by address
  • getInternalTransactions - Get internal transactions by address or transaction hash
  • getERC20Transfers - Get ERC-20 token transfer events by address or contract
  • getERC721Transfers - Get ERC-721 NFT transfer events by address or contract
  • getValidators - Get validator information (for networks with validator sets)
  • getContractCreation - Get contract creation information
  • getContractVerificationStatus - Check contract verification status

Example MCP Interactions

Here are examples of how to interact with blockchain data through the MCP interface:

# Get account balance
What's the ETH balance of vitalik.eth (0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045) on Ethereum?

# Check a token balance
What's the USDC balance of address 0x28C6c06298d514Db089934071355E5743bf21d60 on Ethereum?

# Examine a transaction
Can you analyze transaction 0xdd6d7f687c9821404ae8c2ea7de5cfb5a23fc4c01ef1e7f535748cb147aa76dd on Ethereum?

# Look up block information
What transactions were in Ethereum block 18700000?

# Get contract ABI
Can you show me the ABI for the USDC contract (0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) on Ethereum?

# Analyze contract source code
I need to understand how the Uniswap V3 router works. Can you show me the source code for 0xE592427A0AEce92De3Edee1F18E0157C05861564 on Ethereum?

# Check multiple chains
What's the difference in gas fees between Ethereum and Arbitrum right now?

# Examine token information
Tell me about the tokenomics of the APE token on Ethereum.

Complete List of MCP Tools

The MCP server exposes these tools to AI models:

  • getAccountBalance - Get the balance of an account on a specific blockchain
  • getTokenBalance - Get the token balance of an account on a specific blockchain
  • getTransactionByHash - Get transaction details by hash
  • getBlockByNumber - Get block information by block number
  • getContractABI - Get the ABI for a verified contract
  • getContractSourceCode - Get the source code of a verified contract
  • getTokenInfo - Get information about an ERC20 token
  • getGasPrice - Get current gas price on a specific blockchain
  • getLogs - Get event logs matching specified parameters
  • getTransaction - Get details of a transaction by its hash
  • getTransactionCount - Get the number of transactions sent from an address
  • getTransactionReceipt - Get transaction receipt by transaction hash
  • getBlockTransactionCountByNumber - Get the number of transactions in a block
  • getBlockTransactionCountByHash - Get the number of transactions in a block by block hash
  • getBlockByHash - Get information about a block by its hash
  • getNormalTransactions - Get normal transactions by address
  • getInternalTransactions - Get internal transactions by address or transaction hash
  • getERC20Transfers - Get ERC-20 token transfer events by address or contract
  • getERC721Transfers - Get ERC-721 NFT transfer events by address or contract
  • getValidators - Get validator information (for networks with validator sets)
  • getContractCreation - Get contract creation information
  • getContractVerificationStatus - Check contract verification status

Troubleshooting MCP Integration

If you encounter issues connecting to the MCP server from Cursor:

  1. Verify both servers are running:

    # Check if servers are running
ps aux | grep 1scanmcp

  2. Ensure the correct URL is configured in Cursor

License

MIT License