mcp-etherscan

This MCP server exposes a set of Ethereum data tools powered by Etherscan's API. It provides endpoints to check ETH balances, fetch transaction histories, track ERC20 token transfers, retrieve contract ABIs, monitor gas prices, and resolve ENS names. Clients can communicate with the server via standard MCP stdio transport, making it compatible with MCP-enabled assistants like Claude Desktop and other MCP clients. To use, start the server and connect with an MCP client configured for stdio transport; the client can then invoke the available tools by name (check-balance, get-transactions, get-token-transfers, get-contract-abi, get-gas-prices, get-ens-name) and supply the required inputs such as addresses or contract addresses.

The available tools include:

• check-balance: input an Ethereum address to retrieve the ETH balance in Wei and ETH.
• get-transactions: input an address with an optional limit to obtain recent transactions with timestamps and values.
• get-token-transfers: input an address with an optional limit to view recent ERC20 token transfers and token details.
• get-contract-abi: input a contract address to fetch the contract ABI in JSON format.
• get-gas-prices: input none to receive current gas prices in Gwei (Safe Low, Safe, and Fast).
• get-ens-name: input an Ethereum address to resolve and return the associated ENS name if available.

Prerequisites:

• Node.js v18 or newer
• npm (comes with Node.js)
• An Etherscan API key

Installation steps:

1. Clone the repository and install dependencies

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

2. Create a configuration file with your Etherscan API key

# .env
ETHERSCAN_API_KEY=your_api_key_here

3. Build the project

npm run build

4. Start the server

npm start

The server will run using stdio transport, enabling MCP clients to connect.

Environment variables and configuration:

• ETHERSCAN_API_KEY is required for all API interactions with Etherscan.
• The server communicates via stdio; ensure your MCP client is configured to use the stdio transport.

Common issues:

• Missing or invalid ETHERSCAN_API_KEY will cause API requests to fail. Verify key and format.
• Caution with rate limits from Etherscan; implement proper request pacing in clients if needed.
• Ensure Node.js version meets the minimum requirement (>= 18).

Configuration tips:

• You can adjust environment variables in the deployment environment; the server will read ETHERSCAN_API_KEY on startup.
• If you deploy behind a proxy or in bounded environments, ensure network access to Etherscan endpoints is allowed.