@snjax/etherscan-mcp

MCP (Model Context Protocol) server for Etherscan API v2. Provides blockchain data tools for AI models with multichain support across 60+ EVM-compatible networks.

Features

• Multichain Support: Access data from Ethereum, BSC, Polygon, Arbitrum, Optimism, Base, and 50+ more chains using a single API key
• Comprehensive Tools: 16+ tools covering balances, transactions, contracts, tokens, and more
• Retry Logic: Automatic retry with exponential backoff (1s, 2s, 4s) for API failures
• Well-Documented: Each tool has detailed descriptions for optimal AI model usage

Installation

Using npx (Recommended)

No installation required. Configure your MCP client to run via npx:

{
  "mcpServers": {
    "etherscan": {
      "command": "npx",
      "args": ["-y", "@snjax/etherscan-mcp"],
      "env": {
        "ETHERSCAN_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Global Installation

npm install -g @snjax/etherscan-mcp

Then configure:

{
  "mcpServers": {
    "etherscan": {
      "command": "etherscan-mcp",
      "env": {
        "ETHERSCAN_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Getting an API Key

1. Create an account at Etherscan.io
2. Go to API Keys in your account
3. Create a new API key
4. Use this key for all supported chains (Etherscan API v2 uses unified keys)

Available Tools

Balance Tools

| Tool | Description | |------|-------------| | balanceNative | Get native token (ETH/BNB/MATIC) balance for an address | | balanceERC20 | Get ERC20 token balance for an address |

Transaction Tools

| Tool | Description | |------|-------------| | transaction | Get transaction details by hash | | normalTxsByAddress | List normal transactions for an address | | internalTxsByAddress | List internal transactions (contract calls) | | erc20TxsByAddress | List ERC20 token transfers | | erc721TxsByAddress | List ERC721 (NFT) transfers | | erc1155TxsByAddress | List ERC1155 token transfers |

Account Tools

| Tool | Description | |------|-------------| | fundedBy | Get the address that first funded a given address | | getAddressMetadata | Get name tags, labels, and trust info for an address |

Contract Tools

| Tool | Description | |------|-------------| | getContractAbi | Get ABI for verified contracts | | getContractSourceCode | Get source code for verified contracts | | getContractCreation | Get deployer address and creation tx hash | | getContractBytecode | Get contract bytecode at an address |

Token Tools

| Tool | Description | |------|-------------| | tokenTopHolders | Get top holders for a token contract (requires API Pro) | | getTokenInfo | Get token metadata (name, symbol, decimals, social links) (requires API Pro) |

Supported Chains

Use the chainid parameter to query different networks:

| Chain | Chain ID | |-------|----------| | Ethereum Mainnet | 1 | | Goerli Testnet | 5 | | Sepolia Testnet | 11155111 | | BNB Smart Chain | 56 | | Polygon | 137 | | Arbitrum One | 42161 | | Optimism | 10 | | Base | 8453 | | Avalanche C-Chain | 43114 | | Fantom | 250 | | Cronos | 25 | | Gnosis | 100 |

And 50+ more chains. See Etherscan API v2 documentation for full list.

Usage Examples

Get ETH Balance

Tool: balanceNative
Arguments: { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }

Get Transaction Details

Tool: transaction
Arguments: { "txhash": "0x..." }

Get Contract Source Code

Tool: getContractSourceCode
Arguments: { "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7" }

Query Polygon Network

Tool: balanceNative
Arguments: { "address": "0x...", "chainid": 137 }

Error Handling

The server implements automatic retry logic for:

• HTTP 5xx errors (server errors)
• HTTP 429 (rate limiting)
• Network failures
• Etherscan rate limit messages

Retry delays: 1 second, 2 seconds, 4 seconds (3 attempts total)

Development

# Clone the repository
git clone https://github.com/snjax/etherscan-mcp.git
cd etherscan-mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
ETHERSCAN_API_KEY=your_key node dist/index.js

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related

• Etherscan API Documentation
• Model Context Protocol
• MCP TypeScript SDK