npm package: @snjax/etherscan-mcp
Description: MCP server for Etherscan API v2 - provides blockchain data tools for AI models
Author: Igor Gulamov
Latest version: 1.0.0

# @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:

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

### Global Installation

```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](https://etherscan.io/register)
2. Go to [API Keys](https://etherscan.io/myapikey) 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](https://docs.etherscan.io/etherscan-v2/getting-started/supported-chains) 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

```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](LICENSE) file for details.

## Contributing

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

## Related

- [Etherscan API Documentation](https://docs.etherscan.io/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)