Etherscan MCP Server

A Go implementation of an Etherscan API client for the Model Context Protocol (MCP) that enables LLM applications to access Etherscan blockchain data.

Features

• Access Etherscan API V2 for multi-chain support
• Use a single API key for over 50 supported chains
• Supports various blockchain data retrieval methods:
  • Account balances
  • Block information
  • Contract data (ABI, source code)
  • Gas oracle
  • Token information
  • Transaction data
  • And more

Requirements

• Etherscan API key (get from https://etherscan.io/myapikey)

Installation

1. Clone the repository:

   git clone https://github.com/huahuayu/etherscan-mcp-server.git
   cd etherscan-mcp-server
   

2. Set Etherscan API key env variable:

   ETHERSCAN_API_KEY=your_api_key_here
   

3. Build the server:

   make build
   

4. Install the server:

   make install # install to /usr/local/bin
   

Usage

Default Mode (Standard Input/Output)

Run the server using stdin/stdout communication (default mode):

./bin/etherscan-mcp-server

This mode is useful for direct integration with LLM applications that communicate via stdin/stdout.

MCP config:

{
  "mcpServers": {
    "etherscan-mcp-server": {
      "command": "etherscan-mcp-server",
      "env": {
        "ETHERSCAN_API_KEY": "$your_api_key"
      }
    }
  }
}

Restart cursor and check if it's success:

SSE Mode

Run the server in Server-Sent Events mode:

./bin/etherscan-mcp-server --sse

In SSE mode, the server listens on HTTP and provides an SSE endpoint.

SSE MCP config:

{
  "mcpServers": {
    "etherscan-mcp-server": {
      "url": "http://localhost:4000/sse",
      "env": {
        "ETHERSCAN_API_KEY": "$your_api_key"
      }
    }
  }
}

Server Options

• --sse: Enable SSE server mode (default is stdin/stdout mode)
• --port <port>: Specify the port for SSE server (defaults to PORT env var or 4000)

Connection Endpoints (SSE Mode)

When running in SSE mode, the server provides:

• SSE Endpoint: http://localhost:4000/sse

Supported Chains

50+ chains supported, please refer to the Etherscan V2 Supported Chains for a complete list and their corresponding Chain IDs.

Note on Free Tier Limitations & RPC Fallback: According to Etherscan's supported chains policy, some networks are not available under the Free API plan. These include (but are not limited to):

• BNB Smart Chain (BSC) — Chain ID: 56
• Base — Chain ID: 8453
• Avalanche C-Chain — Chain ID: 43114

For these three chains, this server has a built-in RPC fallback mechanism: when the Etherscan API returns NOTOK, it automatically falls back to free public RPC endpoints using standard JSON-RPC methods. No paid plan is needed for the following tools on these chains:

Tool	JSON-RPC Method
getLatestBlockNumber	eth_blockNumber
getAccountBalance	eth_getBalance
getTokenBalance	eth_call (balanceOf)
getTokenDetails	eth_call (name/symbol/decimals)
getTransactionByHash	eth_getTransactionByHash
getTransactionReceipt	eth_getTransactionReceipt
getTransactionCount	eth_getTransactionCount
executeContractMethod	eth_call

RPC Endpoints Used:

• BSC: https://binance.llamarpc.com
• Base: https://base.llamarpc.com
• Avalanche C-Chain: https://api.avax.network/ext/bc/C/rpc

Other Etherscan-specific tools (e.g., getContractABI, getTransactionsByAddress) still require the Etherscan paid plan for these chains.

Example Queries

You can use natural language queries like these:

Account and Balance Information

• "What's the ETH balance of address 0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae?"
• "Show me the token balance for USDT on address 0x123abc... on BSC"
• "How many transactions has 0xvitalik.eth made from this address?"

Block Information

• "Get information about the latest Polygon block"
• "What are the rewards for miners in block 17000000?"
• "Who mined block 16900000 on Ethereum?"

Contract Interaction

• "Show me the source code at 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984"
• "What's the ABI for the USDC contract on Polygon?"
• "Call the balanceOf function of USDT contract with my address as parameter"

Transaction Information

• "Give me details for transaction 0x123456789abcdef..."
• "Has transaction 0xabcdef... been confirmed yet?"
• "What was the gas price used in transaction 0x789abc..."

Gas and Network

• "What are the current gas prices on Ethereum?"
• "What's the recommended gas price for a fast transaction right now?"
• "How many transactions are pending on Ethereum network?"

Token Information

• "Tell me about the LINK token contract"
• "What ERC-721 NFTs does address 0x123... own?"
• "Show recent token transfers for 0xvitalik.eth"

Custom Queries

• "Track all USDC transfers to Binance hot wallet in the last 1000 blocks"
• "Which addresses received the most ETH in block 17000000?"
• "Compare gas usage on Ethereum vs Arbitrum for similar transactions"

Available Tools

The Etherscan MCP Server provides the following tools for accessing blockchain data:

1. getAccountBalance - Get the balance of an account on a specific blockchain
2. getBlockByNumber - Get block information by block number
3. getBlockRewards - Get block rewards by block number
4. getContractABI - Get the ABI for a verified contract
5. getContractSourceCode - Get the source code of a verified contract
6. executeContractMethod - Execute a read contract function
7. getGasOracle - Get current gas price oracle output
8. getTokenBalance - Get the token balance of an account on a specific blockchain
9. getTokenDetails - Get comprehensive token information
10. getTransactionByHash - Get transaction details by hash
11. getTransactionByBlockNumberAndIndex - Get transaction by block number and index
12. getTransactionCount - Get the number of transactions sent from an address
13. getTransactionReceipt - Check transaction receipt status
14. getTransactionStatus - Check contract execution status
15. getTransactionsByAddress - Get list of transactions by address
16. getInternalTransactionsByAddress - Get list of internal transactions by address
17. getTokenTransfersByAddress - Get list of token transfers by address
18. getERC721Transfers - Get list of ERC721 token transfers by address
19. getLatestBlockNumber - Get the latest block number

Each tool accepts specific parameters and provides blockchain data in a structured format.

License

MIT