@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

$3

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

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

$3

`bash
npm install -g @snjax/etherscan-mcp
`

Then configure:

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

$3

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

$3

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

$3

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

$3

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

$3

| 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

$3

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

$3

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

$3

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

$3

`
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

`bash


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