Etherscan

You run the Etherscan MCP Server to enable large language models and other applications to query Etherscan blockchain data through a unified MCP interface. This Go-based server exposes many data endpoints (balances, blocks, contracts, transactions, tokens, gas, and more) across 50+ chains using a single API key, and it can be used in both stdin/stdout mode and Server-Sent Events (SSE) mode for flexible integration.

How to use

Use two primary deployment patterns: standard input/output (stdio) for direct, app-internal use, and Server-Sent Events (SSE) for a web-friendly, event-driven setup. In stdio mode, you start the server as a normal executable and communicate via standard streams. In SSE mode, the server starts an HTTP endpoint that serves an SSE stream for clients to consume.

Configure your MCP client with one of the following connection methods. If you want a local, self-contained server, use the stdio configuration. If you prefer an HTTP-based, SSE endpoint, use the SSE/http configuration.

// SSE HTTP configuration (http config is shown first in the configuration examples)
{
  "mcpServers": {
    "etherscan_mcp": {
      "url": "http://localhost:4000/sse",
      "env": {
        "ETHERSCAN_API_KEY": "$your_api_key"
      }
    }
   }
}

To run in stdio mode, start the local server binary directly. The command and environment variables are shown below for reference. Use your actual API key in place of the placeholder.

./bin/etherscan-mcp-server

Example stdio MCP configuration snippet (local setup): this config uses the same API key environment variable you set when running the server.

{
  "mcpServers": {
    "etherscan_mcp": {
      "command": "./bin/etherscan-mcp-server",
      "env": {
        "ETHERSCAN_API_KEY": "$your_api_key"
      }
    }
   }
}

How to install

Prerequisites: you need a Go toolchain and a compatible build environment. If you prefer a prebuilt binary, you can also install the binary after building.

Step-by-step installation and start flow:

# 1) Clone the repository
git clone https://github.com/WrldRelief/etherscan-mcp-server.git
cd etherscan-mcp-server

# 2) Set your Etherscan API key in your environment
export ETHERSCAN_API_KEY=your_api_key_here

# 3) Build the server (produces the binary in ./bin or as configured)
make build

# 4) Install the server binary to your system (optional)
make install # installs to /usr/local/bin

Run the server in the default stdio mode directly after building, or run the server in SSE mode if you want an HTTP endpoint.

Configuration and usage notes

The server supports two connection modalities. Use the stdio mode for direct integration with your MCP client or scripts. Use the SSE mode to expose a live HTTP SSE endpoint that clients can subscribe to.

Environment variable you must provide:

ETHERSCAN_API_KEY=your_api_key

Example endpoint in SSE mode (HTTP): the server exposes an SSE endpoint at the following path when started with --sse.

http://localhost:4000/sse

JSON configuration examples for MCP clients are shown here. The http configuration uses the SSE endpoint and includes the API key, while the stdio configuration runs the local binary with the API key set in the environment.

{
  "mcpServers": {
    "etherscan_mcp": {
      "url": "http://localhost:4000/sse",
      "env": {
        "ETHERSCAN_API_KEY": "$your_api_key"
      }
    }
   }
}

{
  "mcpServers": {
    "etherscan_mcp": {
      "command": "./bin/etherscan-mcp-server",
      "env": {
        "ETHERSCAN_API_KEY": "$your_api_key"
      }
    }
   }
}

Notes and tips

Supported data sources and actions cover accounts, blocks, contracts (ABI and source), gas prices, tokens, transactions, and related data. You can query details such as balance, block information, contract ABIs, token details, and transaction status across 50+ chains.

Remember to keep your API key secure. Do not expose it in client-side code or public repositories. If you rotate keys, update the environment variable in your MCP client configuration accordingly.

Available tools

getAccountBalance

Get the balance of an account on a specific blockchain

getBlockByNumber

Get block information by block number

getBlockRewards

Get block rewards by block number

getContractABI

Get the ABI for a verified contract

getContractSourceCode

Get the source code of a verified contract

executeContractMethod

Execute a read contract function

getGasOracle

Get current gas price oracle output

getTokenBalance

Get the token balance of an account on a specific blockchain

getTokenDetails

Get comprehensive token information

getTransactionByHash

Get transaction details by hash

getTransactionByBlockNumberAndIndex

Get transaction by block number and index

getTransactionCount

Get the number of transactions sent from an address

getTransactionReceipt

Check transaction receipt status

getTransactionStatus

Check contract execution status

getTransactionsByAddress

Get list of transactions by address

getInternalTransactionsByAddress

Get list of internal transactions by address

getTokenTransfersByAddress

Get list of token transfers by address

getERC721Transfers

Get list of ERC721 token transfers by address

getLatestBlockNumber

Get the latest block number