dennisonbertram/mcp-etherscan-server

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:

See 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

Token Tools (V2)

Contract Tools

Block Tools

Network Tools (V2)

Utility Tools

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:

• - Overview of all endpoints
• - Complete list of 72+ networks

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