Etherscan MCP Server

基于 Model Context Protocol 的 Etherscan API 服务器，支持在 Claude Desktop、Cursor 等 AI 助手中直接查询区块链数据。

支持 60+ EVM 链，通过 chainId 参数动态切换。

安装

# 无需全局安装，直接在客户端配置中使用
npx -y @everimbaq/etherscan-mcp

功能

所有工具都支持 chainId 参数，默认为 1 (Ethereum Mainnet)。

Account (账户)

• get_balance - 获取地址的原生代币余额
• get_multi_balance - 批量获取多个地址的余额
• get_transactions - 获取地址的普通交易列表
• get_internal_transactions - 获取地址的内部交易列表
• get_erc20_transfers - 获取ERC20代币转账记录
• get_erc721_transfers - 获取ERC721 NFT转账记录
• get_erc1155_transfers - 获取ERC1155代币转账记录
• get_address_token_balance - 获取地址持有的所有ERC20代币
• get_address_nft_balance - 获取地址持有的所有NFT

Contract (合约)

• get_contract_abi - 获取已验证合约的ABI
• get_contract_source - 获取已验证合约的源代码
• get_contract_creation - 获取合约的创建者和创建交易

Transaction (交易)

• get_tx_receipt_status - 获取交易收据状态
• get_tx_status - 获取交易执行状态

Block (区块)

• get_block_reward - 获取区块奖励信息
• get_block_countdown - 获取到达指定区块的预估时间
• get_block_by_timestamp - 根据时间戳获取区块号

Stats (统计)

• get_eth_supply - 获取原生代币总供应量
• get_eth_price - 获取原生代币当前价格

Gas Tracker (Gas追踪)

• get_gas_oracle - 获取当前Gas价格建议

Token (代币)

• get_token_supply - 获取ERC20代币总供应量
• get_token_balance - 获取地址的ERC20代币余额
• get_token_info - 获取代币详细信息
• get_token_holder_list - 获取代币持有者列表

Proxy/Geth (底层RPC)

• eth_block_number - 获取最新区块号
• eth_get_block_by_number - 根据区块号获取区块详情
• eth_get_transaction_by_hash - 根据哈希获取交易详情
• eth_get_transaction_receipt - 获取交易收据
• eth_get_code - 获取合约字节码
• eth_call - 执行合约只读调用

Logs (日志)

• get_logs - 获取合约事件日志

支持的链

| Chain | chainId | Chain | chainId | |-------|---------|-------|---------| | Ethereum | 1 | Arbitrum One | 42161 | | Sepolia | 11155111 | Arbitrum Nova | 42170 | | Polygon | 137 | Optimism | 10 | | BNB Smart Chain | 56 | Base | 8453 | | Avalanche C-Chain | 43114 | Linea | 59144 | | Gnosis | 100 | zkSync | 324 | | Scroll | 534352 | Blast | 81457 | | Mantle | 5000 | Celo | 42220 | | Moonbeam | 1284 | Sonic | 146 |

完整列表参见 Etherscan Supported Chains

快速开始

使用 npx（推荐）

无需安装，直接在 MCP 客户端配置中使用：

npx -y @everimbaq/etherscan-mcp

本地开发

npm install
npm run build

配置

环境变量

| 变量名 | 必需 | 说明 | |--------|------|------| | ETHERSCAN_API_KEY | 是 | Etherscan API Key（获取方式） |

Claude Desktop 配置

编辑配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下内容：

{
  "mcpServers": {
    "etherscan": {
      "command": "npx",
      "args": ["-y", "@everimbaq/etherscan-mcp"],
      "env": {
        "ETHERSCAN_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor 配置

在 ~/.cursor/mcp.json 中添加:

{
  "mcpServers": {
    "etherscan": {
      "command": "npx",
      "args": ["-y", "@everimbaq/etherscan-mcp"],
      "env": {
        "ETHERSCAN_API_KEY": "your-api-key"
      }
    }
  }
}

配置完成后，重启客户端即可使用。

使用示例

配置完成后，在 Claude/Cursor 中可以直接使用自然语言查询：

查询地址 0x... 在以太坊上的余额

查询 Vitalik.eth 在 Polygon 上的最近 10 笔交易

获取 USDT 合约的 ABI (chainId: 1)

查询当前以太坊 Gas 价格建议

查询 0x... 地址持有的所有 ERC20 代币

AI 助手会自动调用对应的工具：

// 查询余额
get_balance(address: "0x...", chainId: 1)

// 查询交易
get_transactions(address: "0x...", chainId: 137, offset: 10)

// 获取合约 ABI
get_contract_abi(address: "0xdac17f958d2ee523a2206206994597c13d831ec7", chainId: 1)

// Gas 价格
get_gas_oracle(chainId: 1)

// 代币余额
get_address_token_balance(address: "0x...", chainId: 1)

开发与测试

本地开发

# 克隆项目
git clone https://github.com/your-username/etherscan-mcp.git
cd etherscan-mcp

# 安装依赖
npm install

# 设置环境变量
export ETHERSCAN_API_KEY="your-api-key"

# 运行开发模式
npm run dev

# 使用 MCP Inspector 调试
npm run inspect

评估测试

项目包含 evaluation.xml 用于测试 MCP Server 功能。可配合 mcp-builder evaluation.py 运行评估：

python evaluation.py -t stdio -c node -a dist/index.js -e ETHERSCAN_API_KEY=your-key evaluation.xml

发布新版本

# 构建
npm run build

# 升级版本号
npm version patch  # 或 minor, major

# 发布到 npm
npm publish --access public

获取 API Key

1. 访问 Etherscan 注册账号
2. 登录后前往 API Keys 页面
3. 创建一个新的 API Key

License

MIT