Content
# Etherscan MCP Server
A Go implementation of an Etherscan API client for the [Model Context Protocol (MCP)](https://github.com/mark3labs/mcp-go) 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](https://docs.etherscan.io/etherscan-v2/getting-started/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:
```bash
git clone https://github.com/huahuayu/etherscan-mcp-server.git
cd etherscan-mcp-server
```
2. Set Etherscan API key env variable:
```bash
ETHERSCAN_API_KEY=your_api_key_here
```
3. Build the server:
```bash
make build
```
4. Install the server:
```bash
make install # install to /usr/local/bin
```
## Usage
### Default Mode (Standard Input/Output)
Run the server using stdin/stdout communication (default mode):
```bash
./bin/etherscan-mcp-server
```
This mode is useful for direct integration with LLM applications that communicate via stdin/stdout.
MCP config:
```json
{
"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:
```bash
./bin/etherscan-mcp-server --sse
```
In SSE mode, the server listens on HTTP and provides an SSE endpoint.
SSE MCP config:
```json
{
"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](https://docs.etherscan.io/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](https://docs.etherscan.io/supported-chains), 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
