Etherscan MCP server for AI agents

The Etherscan MCP Server is a Go implementation that allows LLM applications to access blockchain data through the Etherscan API. It implements the Model Context Protocol (MCP) to enable natural language queries against Etherscan's extensive blockchain data services across more than 50 supported chains.

Requirements

Etherscan API key (obtain one from Etherscan)

Installation

Step 1: Clone the Repository

git clone https://github.com/WrldRelief/etherscan-mcp-server.git
cd etherscan-mcp-server

Step 2: Set Up Your API Key

export ETHERSCAN_API_KEY=your_api_key_here

Step 3: Build and Install

make build
make install  # installs to /usr/local/bin

Usage Options

Default Mode (Standard Input/Output)

Run the server using stdin/stdout communication:

./bin/etherscan-mcp-server

This mode is ideal for direct integration with LLM applications that communicate via stdin/stdout.

MCP Configuration for Default Mode

{
  "mcpServers": {
    "etherscan-mcp-server": {
      "command": "etherscan-mcp-server",
      "env": {
        "ETHERSCAN_API_KEY": "$your_api_key"
      }
    }
  }
}

SSE Mode

Run the server in Server-Sent Events mode:

./bin/etherscan-mcp-server --sse

In SSE mode, the server listens on HTTP and provides an SSE endpoint.

MCP Configuration for SSE Mode

{
  "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

Example Queries

You can use natural language queries to access blockchain data:

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..."

Available Tools

The Etherscan MCP Server provides these tools for accessing blockchain data:

getAccountBalance - Get account balance on a specific blockchain
getBlockByNumber - Get block information by number
getBlockRewards - Get block rewards by number
getContractABI - Get ABI for verified contracts
getContractSourceCode - Get source code of verified contracts
executeContractMethod - Execute read contract functions
getGasOracle - Get current gas prices
getTokenBalance - Get token balances for accounts
getTokenDetails - Get comprehensive token information
getTransactionByHash - Get transaction details by hash
getTransactionReceipt - Check transaction receipt status
getTransactionStatus - Check contract execution status
getTransactionsByAddress - Get transactions by address
getInternalTransactionsByAddress - Get internal transactions by address
getTokenTransfersByAddress - Get token transfers by address
getERC721Transfers - Get NFT transfers by address
getLatestBlockNumber - Get the latest block number

Each tool accepts specific parameters and provides blockchain data in a structured format.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "etherscan-mcp-server" '{"command":"etherscan-mcp-server","env":{"ETHERSCAN_API_KEY":"$your_api_key"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "etherscan-mcp-server": {
            "command": "etherscan-mcp-server",
            "env": {
                "ETHERSCAN_API_KEY": "$your_api_key"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "etherscan-mcp-server": {
            "command": "etherscan-mcp-server",
            "env": {
                "ETHERSCAN_API_KEY": "$your_api_key"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect