Etherscan MCP Server

A Model Context Protocol (MCP) server that integrates with the Etherscan API, providing access to Ethereum blockchain data through standardized MCP tools.

Features

This MCP server exposes all major Etherscan API endpoints as MCP tools, organized into the following categories:

✨ Multichain Support: All tools support Etherscan API V2's multichain functionality via the optional chainid parameter. Query data from Ethereum (1), BSC (56), Polygon (137), Base, Arbitrum, and 60+ other supported chains!

🧱 Accounts

• get_balance - Get ETH balance for a single address
• get_multiple_balances - Get ETH balances for multiple addresses
• get_transactions - Get list of normal transactions for an address

⛓️ Blocks

• get_block_reward - Get block and uncle rewards by block number
• get_block_countdown - Get estimated time until a block is mined
• get_block_number_by_timestamp - Get block number closest to a timestamp

💸 Transactions

• get_tx_status - Get transaction execution status
• get_internal_transactions - Get internal transactions by hash or address

🧠 Contracts

• get_abi - Get contract ABI for verified contracts
• get_source_code - Get contract source code for verified contracts

⛽ Gas Tracker

• get_gas_oracle - Get current gas prices (Safe, Propose, Fast)

💰 Tokens

• get_token_supply - Get total supply of an ERC-20 token
• get_token_balance - Get ERC-20 token balance for an address

🧮 Stats

• get_eth_price - Get current ETH price in USD and BTC
• get_node_count - Get total number of Ethereum nodes

Prerequisites

• Node.js 18+
• npm or yarn
• Etherscan API key (Get one here)

Installation

For Local Development

1. Clone or download this repository

2. Install dependencies:

npm install

1. Set your Etherscan API key as an environment variable:

# Windows (PowerShell)
$env:ETHERSCAN_API_KEY="your-api-key-here"

# Windows (CMD)
set ETHERSCAN_API_KEY=your-api-key-here

# Linux/Mac
export ETHERSCAN_API_KEY=your-api-key-here

For Smithery Deployment

When deploying to Smithery, users will be prompted to provide their own ETHERSCAN_API_KEY as an environment variable in the Smithery configuration. The server will automatically use the provided API key.

Building

Compile TypeScript to JavaScript:

npm run build

Usage

Running the Server

The server uses stdio transport and should be configured in your MCP client:

npm start

MCP Client Configuration

Add this server to your MCP client configuration (e.g., in Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "etherscan-mcp": {
      "command": "node",
      "args": ["path/to/etherscan-mcp/dist/index.js"],
      "env": {
        "ETHERSCAN_API_KEY": "your-api-key-here"
      }
    }
  }
}

Important: Always provide your own Etherscan API key. Never commit API keys to version control.

Example Tool Usage

Once connected to an MCP client, you can use tools like:

• Get balance: get_balance with address: "0x..."
• Get transactions: get_transactions with address: "0x..." and optional pagination
• Get gas prices: get_gas_oracle (no parameters needed)
• Get token balance: get_token_balance with contractaddress and address

Multichain Usage

All tools support the optional chainid parameter for multichain queries:

• Ethereum Mainnet: chainid: 1 (default if omitted)
• BNB Smart Chain: chainid: 56
• Polygon: chainid: 137
• Base: chainid: 8453
• Arbitrum: chainid: 42161

Example: Query BSC balance with get_balance({ address: "0x...", chainid: 56 })

See the Etherscan API documentation for the full list of supported chains.

Development

Project Structure

.
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Scripts

• npm run build - Compile TypeScript
• npm start - Run the compiled server
• npm run dev - Build and run in one command

API Rate Limits

Etherscan API has rate limits based on your API key tier:

• Free tier: 5 calls/second
• Standard tier: 10 calls/second
• Advanced tier: 15 calls/second

The server will return errors if rate limits are exceeded.

Error Handling

The server validates all required parameters and returns appropriate MCP errors:

• InvalidParams - Missing or invalid parameters
• MethodNotFound - Unknown tool name
• InternalError - API call failures or other errors

License

MIT

EtherscanMcp