Etherscan MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to the Etherscan API V2. This server exposes 65+ tools covering all major Etherscan API endpoints including accounts, blocks, contracts, gas tracking, tokens, logs, statistics, and Ethereum JSON-RPC proxy methods.

Features

• Complete API Coverage: Access to all Etherscan V2 API endpoints
• Multi-Chain Support: Works with 60+ EVM-compatible chains via chain ID parameter
• HTTP Transport: RESTful HTTP API with Server-Sent Events (SSE) for MCP protocol
• CORS Enabled: Cross-origin requests supported out of the box
• MCP Protocol: Standard MCP server implementation for seamless integration
• TypeScript: Fully typed for better development experience
• Error Handling: Comprehensive error handling with descriptive messages
• Organized Structure: Clean separation of tools, handlers, and utilities

Supported API Categories

Account APIs (11 tools)

• Native token balances (single and multi-address)
• Historical balance queries
• Transaction lists (normal, internal, token transfers)
• ERC-20, ERC-721, ERC-1155 token transfers
• Mined blocks
• Beacon chain withdrawals
• Address funding source

Block APIs (8 tools)

• Block and uncle rewards
• Block countdown estimates
• Block number by timestamp
• Daily block statistics (size, count, rewards, time)

Contract APIs (3 tools)

• Contract ABI retrieval
• Source code access
• Contract creator information

Gas Tracker APIs (5 tools)

• Gas price oracle (safe, propose, fast)
• Confirmation time estimates
• Daily gas statistics (limit, usage, price)

Token APIs (11 tools)

• Token supply and balances
• Historical token data
• Token holder lists and rankings
• Token metadata and info
• NFT inventory tracking

Logs APIs (1 tool)

• Event log filtering by address, topics, and block range

Statistics APIs (12 tools)

• ETH supply and price
• Network statistics
• Daily metrics (transactions, fees, addresses)
• Hash rate and difficulty
• Node counts and blockchain size

Proxy APIs (14 tools)

• Complete Ethereum JSON-RPC support
• Block and transaction queries
• Contract calls and code retrieval
• Gas estimation
• Raw transaction broadcasting

Installation

1. Clone or download this repository

2. Install dependencies:

npm install

3. Create a .env file based on .env.example:

cp .env.example .env

4. Add your Etherscan API key to .env:

ETHERSCAN_API_KEY=your_api_key_here

Get your API key from: https://etherscan.io/myapikey

Usage

Build the project:

npm run build

Run in development mode:

npm run dev

Run in production:

npm start

The server will start on http://localhost:3000 by default.

HTTP Endpoints

Once running, the server exposes these endpoints:

• GET /health - Health check endpoint, returns server status and tool count
• POST /mcp - Initialize MCP session and send JSON-RPC requests
• GET /mcp - Establish SSE stream for an existing session
• DELETE /mcp - Terminate an MCP session

Example Health Check

curl http://localhost:3000/health
# Response: {"status":"ok","tools":65,"transport":"streamable-http","protocol":"MCP","sessions":0}

MCP Protocol Flow

1. Initialize Session - POST to /mcp without session ID
2. Get Session ID - Receive mcp-session-id header in response
3. Send Requests - POST to /mcp with session ID header
4. Stream Events - GET /mcp with session ID for SSE notifications
5. Terminate - DELETE /mcp with session ID when done

Configuration

Edit .env to configure the server:

• ETHERSCAN_API_KEY: Your Etherscan API key (required)
• DEFAULT_CHAIN_ID: Default chain ID (default: 1 for Ethereum mainnet)
• PORT: Server port (default: 3000)
• HOST: Server host (default: localhost)

CORS Configuration

CORS is enabled by default with origin: '*' for development. For production:

1. Edit src/server.ts
2. Change the CORS configuration:

app.use(cors({
  origin: 'https://your-domain.com', // Specific origin
  methods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Accept', 'mcp-session-id'],
  exposedHeaders: ['mcp-session-id'],
  credentials: true // If using cookies/auth
}));

Supported Chain IDs

The server supports 60+ chains. Common chain IDs:

• 1: Ethereum Mainnet
• 5: Goerli Testnet
• 11155111: Sepolia Testnet
• 56: BNB Smart Chain
• 137: Polygon
• 42161: Arbitrum One
• 10: Optimism
• 8453: Base
• 43114: Avalanche C-Chain

MCP Integration

This server implements the Model Context Protocol over HTTP using the modern StreamableHTTP transport (current MCP protocol). It provides session-based communication with SSE streaming support.

Connecting to the Server

MCP clients should follow this flow:

# 1. Initialize session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'

# 2. Extract mcp-session-id from response headers

# 3. Send requests with session ID
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Example Tool Usage

All tools follow the naming pattern etherscan_<category>_<action>.

Get ETH Balance

{
  "name": "etherscan_account_balance",
  "arguments": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "chainid": "1"
  }
}

Get Gas Oracle

{
  "name": "etherscan_gas_oracle",
  "arguments": {
    "chainid": "1"
  }
}

Get Contract ABI

{
  "name": "etherscan_contract_abi",
  "arguments": {
    "address": "0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413",
    "chainid": "1"
  }
}

Get Transaction Receipt

{
  "name": "etherscan_proxy_get_transaction_receipt",
  "arguments": {
    "txhash": "0x...",
    "chainid": "1"
  }
}

Project Structure

etherscan_mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server implementation
│   ├── config.ts             # Configuration management
│   ├── types/                # TypeScript type definitions
│   │   ├── index.ts
│   │   └── etherscan.ts
│   ├── tools/                # MCP tool definitions
│   │   ├── account.ts
│   │   ├── block.ts
│   │   ├── contract.ts
│   │   ├── gas.ts
│   │   ├── token.ts
│   │   ├── logs.ts
│   │   ├── stats.ts
│   │   └── proxy.ts
│   ├── handlers/             # Tool execution handlers
│   │   ├── account.ts
│   │   ├── block.ts
│   │   ├── contract.ts
│   │   ├── gas.ts
│   │   ├── token.ts
│   │   ├── logs.ts
│   │   ├── stats.ts
│   │   └── proxy.ts
│   └── utils/
│       ├── api.ts            # Etherscan API client
│       └── schemas.ts        # Zod validation schemas
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

API Rate Limits

Etherscan API has rate limits based on your plan:

• Free: 5 calls/second
• Standard: 10 calls/second
• Advanced: 15 calls/second
• Professional: 20 calls/second

The server does not implement rate limiting - ensure your client respects these limits.

Error Handling

The server provides detailed error messages:

• Missing API key
• Invalid parameters
• Etherscan API errors
• Network errors

Errors are returned in MCP error format with appropriate error codes.

Development

Adding New Tools

1. Define the tool in the appropriate src/tools/*.ts file
2. Add the handler logic in the corresponding src/handlers/*.ts file
3. Create Zod schemas in src/utils/schemas.ts if needed
4. The server will automatically register and route the new tool

License

MIT

Resources

• Etherscan API Documentation
• Model Context Protocol
• Get Etherscan API Key

Contributing

Contributions are welcome! Please ensure:

• TypeScript types are properly defined
• Error handling is comprehensive
• Tool names follow the etherscan_<category>_<action> pattern
• Documentation is updated for new features