MCP Etherscan Server

An MCP (Model Context Protocol) server that provides Ethereum blockchain data tools via Etherscan's V2 API. Supports 72+ blockchain networks with a single API key, including Ethereum, Arbitrum, Base, Polygon, Optimism, and many more.

Features

Core Features

• Multi-Chain Support: 72+ networks (Ethereum, L2s, sidechains, testnets)
• Balance Checking: Get native token balance for any address
• Transaction History: View recent transactions with detailed information
• Token Transfers: Track ERC20/ERC721/ERC1155 token transfers
• Contract Tools: Fetch ABIs, source code, verify contracts
• Gas Prices: Monitor current gas prices across networks
• ENS Resolution: Resolve Ethereum addresses to ENS names

V2 API Features (New)

• Beacon Withdrawals: Track ETH 2.0 staking withdrawals
• Token Info: Get comprehensive token metadata and social links
• Token Holders: View top holders for any token
• Token Portfolio: Get all token balances for an address
• Event Logs: Query contract events with advanced filtering
• Network Stats: ETH supply, price, market cap data
• Daily Statistics: Historical transaction counts

Supported Networks

72+ networks including:

Category	Networks
Ethereum	Mainnet, Sepolia, Holesky, Hoodi
Layer 2	Arbitrum, Optimism, Base, zkSync, Scroll, Linea, Mantle, Blast
Sidechains	Polygon, BNB Chain, Avalanche, Fantom, Gnosis
Emerging	Berachain, Sonic, Taiko, Unichain, World, Abstract

See docs/api/NETWORK_SUPPORT.md for the complete list.

Prerequisites

• Node.js >= 18
• An Etherscan API key (get one at https://etherscan.io/apis)
• One API key works for all 72+ networks!

Installation

1. Clone the repository:

git clone [your-repo-url]
cd mcp-etherscan-server

2. Install dependencies:

npm install

3. Create a .env file in the root directory:

ETHERSCAN_API_KEY=your_api_key_here

4. Build the project:

npm run build

Running the Server

Start the server:

npm start

The server will run on stdio, making it compatible with MCP clients like Claude Desktop.

How It Works

This server implements the Model Context Protocol (MCP) to provide tools for interacting with Ethereum blockchain data through Etherscan's API. Each tool is exposed as an MCP endpoint that can be called by compatible clients.

Available Tools (24 Total)

Account Tools

Tool	Description
check-balance	Get native token balance for any address
get-transactions	Recent transactions with timestamps and values
get-token-transfers	ERC20 token transfers with token details
get-internal-transactions	Internal transactions with trace details
get-mined-blocks	Blocks mined by an address with rewards
get-beacon-withdrawals	ETH 2.0 staking withdrawals

Token Tools (V2)

Tool	Description
get-token-info	Comprehensive token metadata and social links
get-token-holders	Top token holders with balances
get-token-portfolio	All token balances for an address

Contract Tools

Tool	Description
get-contract-abi	Contract ABI in JSON format
get-contract-source	Verified source code and metadata
get-contract-creation	Creator address and deployment tx
verify-contract	Submit contract for verification
check-verification	Check verification status
verify-proxy	Verify proxy contract
get-verified-contracts	Recently verified contracts

Block Tools

Tool	Description
get-block-details	Block info (hash, gas, transactions)
get-block-reward	Block and uncle rewards

Network Tools (V2)

Tool	Description
get-gas-prices	Current gas prices in Gwei
get-network-stats	ETH supply, price, market cap
get-daily-stats	Daily transaction statistics
get-logs	Event logs with topic filtering
list-networks	All 72+ supported networks

Utility Tools

Tool	Description
get-ens-name	Resolve address to ENS name

Using with Claude Desktop

To add this server to Claude Desktop:

1. In Claude Desktop settings, add this server configuration:

   {
     "mcpServers": {
       "etherscan": {
         "command": "node",
         "args": ["/path/to/mcp-etherscan-server/build/index.js"],
         "env": {
           "ETHERSCAN_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   

2. The Etherscan tools will now be available in your Claude conversations

Example Usage in Claude

Check the balance of 0x742d35Cc6634C0532925a3b844Bc454e4438f44e on Ethereum

Show me recent transactions for vitalik.eth on mainnet

Get token holders for USDC on Polygon

List all supported networks

Specifying Networks

All tools support a network parameter. You can use:

• Network slug: "ethereum", "polygon", "arbitrum", "base"
• Chain ID: 1, 137, 42161, 8453

Check balance of 0x... on arbitrum
Check balance of 0x... with chainId 42161

Documentation

Comprehensive API documentation is available in the docs/ directory:

• API Index - Overview of all endpoints
• Network Support - Complete list of 72+ networks
• Account Endpoints
• Token Endpoints
• Contract Endpoints
• Block Endpoints
• Gas Tracker
• Stats Endpoints
• Logs Endpoints

Development

Project Structure

src/
├── index.ts              # Entry point
├── server.ts             # MCP server with 24 tools
├── config/
│   └── networks.ts       # 72+ network configurations
├── api/
│   └── v2-request-builder.ts  # V2 API request builder
├── services/
│   └── etherscanService.ts    # Etherscan API service
├── types/
│   └── index.ts          # TypeScript type definitions
└── __tests__/            # Test suites

Building

npm run build    # Compile TypeScript
npm run test     # Run tests
npm start        # Start server

Adding New Networks

Networks are configured in src/config/networks.ts. The V2 API automatically handles the chainid parameter.

V2 API Migration

This server uses Etherscan's V2 API which:

• Uses a unified endpoint: https://api.etherscan.io/v2/api
• Requires chainid parameter for all requests
• Supports 72+ networks with a single API key
• Deprecates the old per-network API URLs

See Etherscan V2 Migration Guide for details.

License

MIT License - See LICENSE file for details