# MCP Etherscan Server

An MCP (Model Context Protocol) server that provides Ethereum blockchain data tools via **Etherscan's V2 API**. Supports **72+ blockchain networks** with a single API key, including Ethereum, Arbitrum, Base, Polygon, Optimism, and many more.

## Features

### Core Features
- **Multi-Chain Support**: 72+ networks (Ethereum, L2s, sidechains, testnets)
- **Balance Checking**: Get native token balance for any address
- **Transaction History**: View recent transactions with detailed information
- **Token Transfers**: Track ERC20/ERC721/ERC1155 token transfers
- **Contract Tools**: Fetch ABIs, source code, verify contracts
- **Gas Prices**: Monitor current gas prices across networks
- **ENS Resolution**: Resolve Ethereum addresses to ENS names

### V2 API Features (New)
- **Beacon Withdrawals**: Track ETH 2.0 staking withdrawals
- **Token Info**: Get comprehensive token metadata and social links
- **Token Holders**: View top holders for any token
- **Token Portfolio**: Get all token balances for an address
- **Event Logs**: Query contract events with advanced filtering
- **Network Stats**: ETH supply, price, market cap data
- **Daily Statistics**: Historical transaction counts

## Supported Networks

72+ networks including:

| Category | Networks |
|----------|----------|
| **Ethereum** | Mainnet, Sepolia, Holesky, Hoodi |
| **Layer 2** | Arbitrum, Optimism, Base, zkSync, Scroll, Linea, Mantle, Blast |
| **Sidechains** | Polygon, BNB Chain, Avalanche, Fantom, Gnosis |
| **Emerging** | Berachain, Sonic, Taiko, Unichain, World, Abstract |

See [docs/api/NETWORK_SUPPORT.md](docs/api/NETWORK_SUPPORT.md) for the complete list.

## Prerequisites

- Node.js >= 18
- An Etherscan API key (get one at https://etherscan.io/apis)
- **One API key works for all 72+ networks!**

## Installation

1. Clone the repository:
```bash
git clone [your-repo-url]
cd mcp-etherscan-server
```

2. Install dependencies:
```bash
npm install
```

3. Create a `.env` file in the root directory:
```bash
ETHERSCAN_API_KEY=your_api_key_here
```

4. Build the project:
```bash
npm run build
```

## Running the Server

Start the server:
```bash
npm start
```

The server will run on stdio, making it compatible with MCP clients like Claude Desktop.

## How It Works

This server implements the Model Context Protocol (MCP) to provide tools for interacting with Ethereum blockchain data through Etherscan's API. Each tool is exposed as an MCP endpoint that can be called by compatible clients.

### Available Tools (24 Total)

#### Account Tools
| Tool | Description |
|------|-------------|
| `check-balance` | Get native token balance for any address |
| `get-transactions` | Recent transactions with timestamps and values |
| `get-token-transfers` | ERC20 token transfers with token details |
| `get-internal-transactions` | Internal transactions with trace details |
| `get-mined-blocks` | Blocks mined by an address with rewards |
| `get-beacon-withdrawals` | ETH 2.0 staking withdrawals |

#### Token Tools (V2)
| Tool | Description |
|------|-------------|
| `get-token-info` | Comprehensive token metadata and social links |
| `get-token-holders` | Top token holders with balances |
| `get-token-portfolio` | All token balances for an address |

#### Contract Tools
| Tool | Description |
|------|-------------|
| `get-contract-abi` | Contract ABI in JSON format |
| `get-contract-source` | Verified source code and metadata |
| `get-contract-creation` | Creator address and deployment tx |
| `verify-contract` | Submit contract for verification |
| `check-verification` | Check verification status |
| `verify-proxy` | Verify proxy contract |
| `get-verified-contracts` | Recently verified contracts |

#### Block Tools
| Tool | Description |
|------|-------------|
| `get-block-details` | Block info (hash, gas, transactions) |
| `get-block-reward` | Block and uncle rewards |

#### Network Tools (V2)
| Tool | Description |
|------|-------------|
| `get-gas-prices` | Current gas prices in Gwei |
| `get-network-stats` | ETH supply, price, market cap |
| `get-daily-stats` | Daily transaction statistics |
| `get-logs` | Event logs with topic filtering |
| `list-networks` | All 72+ supported networks |

#### Utility Tools
| Tool | Description |
|------|-------------|
| `get-ens-name` | Resolve address to ENS name |

## Using with Claude Desktop

To add this server to Claude Desktop:

1. In Claude Desktop settings, add this server configuration:
   ```json
   {
     "mcpServers": {
       "etherscan": {
         "command": "node",
         "args": ["/path/to/mcp-etherscan-server/build/index.js"],
         "env": {
           "ETHERSCAN_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   ```

2. The Etherscan tools will now be available in your Claude conversations

### Example Usage in Claude

```
Check the balance of 0x742d35Cc6634C0532925a3b844Bc454e4438f44e on Ethereum
```

```
Show me recent transactions for vitalik.eth on mainnet
```

```
Get token holders for USDC on Polygon
```

```
List all supported networks
```

### Specifying Networks

All tools support a `network` parameter. You can use:
- Network slug: `"ethereum"`, `"polygon"`, `"arbitrum"`, `"base"`
- Chain ID: `1`, `137`, `42161`, `8453`

```
Check balance of 0x... on arbitrum
Check balance of 0x... with chainId 42161
```

## Documentation

Comprehensive API documentation is available in the `docs/` directory:

- [API Index](docs/api/INDEX.md) - Overview of all endpoints
- [Network Support](docs/api/NETWORK_SUPPORT.md) - Complete list of 72+ networks
- [Account Endpoints](docs/api/account-endpoints.md)
- [Token Endpoints](docs/api/tokens-endpoints.md)
- [Contract Endpoints](docs/api/contracts-endpoints.md)
- [Block Endpoints](docs/api/blocks-endpoints.md)
- [Gas Tracker](docs/api/gas-tracker-endpoints.md)
- [Stats Endpoints](docs/api/stats-endpoints.md)
- [Logs Endpoints](docs/api/logs-endpoints.md)

## Development

### Project Structure

```
src/
├── index.ts              # Entry point
├── server.ts             # MCP server with 24 tools
├── config/
│   └── networks.ts       # 72+ network configurations
├── api/
│   └── v2-request-builder.ts  # V2 API request builder
├── services/
│   └── etherscanService.ts    # Etherscan API service
├── types/
│   └── index.ts          # TypeScript type definitions
└── __tests__/            # Test suites
```

### Building

```bash
npm run build    # Compile TypeScript
npm run test     # Run tests
npm start        # Start server
```

### Adding New Networks

Networks are configured in `src/config/networks.ts`. The V2 API automatically handles the `chainid` parameter.

## V2 API Migration

This server uses Etherscan's V2 API which:
- Uses a unified endpoint: `https://api.etherscan.io/v2/api`
- Requires `chainid` parameter for all requests
- Supports 72+ networks with a single API key
- Deprecates the old per-network API URLs

See [Etherscan V2 Migration Guide](https://docs.etherscan.io/v2-migration) for details.

## License

MIT License - See LICENSE file for details