etherscan-mcp-server

Etherscan MCP 服务

一个适用于 Etherscan 的 MCP 服务 — 将任何兼容 MCP 的客户端连接到 Ethereum 区块链浏览器。

这是什么？

一个 MCP（Model Context Protocol） 服务，通过 Etherscan 的 Ethereum 区块链浏览器 API，为 AI 助手和 Agent 提供访问权限 — 可通过自然语言查询 ETH 余额、ERC-20 代币余额、交易历史、合约 ABI 和 Gas 价格。

可与 Claude Desktop、Cursor、Windsurf、Cline、Continue 或任何兼容 MCP 的客户端搭配使用，以检查钱包、审计合约和分析链上活动。

为什么使用它？

• 无需 API 密钥 — 使用 Etherscan 免费套餐即可开箱即用（无密钥时限制为约每 5 秒 1 次调用）
• 支持可选 API 密钥 — 设置 ETHERSCAN_API_KEY 即可达到每秒 5 次调用并获取完整结果
• 内置 8 个工具 — 涵盖最常见的链上查询
• 简洁的 Markdown 输出 — 结果在聊天中易于阅读
• 自动限制速率 — 遵守免费套餐限制，并在遇到 429 错误时重试

工具

工具	描述
get_eth_balance	获取某个地址的原生 ETH 余额
get_token_balances	获取某个地址的所有 ERC-20 代币余额
get_transaction	根据哈希获取交易的完整详情
get_transactions_by_address	获取某个地址的普通（外部）交易
get_erc20_transfers	获取某个地址的 ERC-20 代币转账事件
get_internal_transactions	获取某个地址的内部（合约调用）交易
get_contract_abi	获取已验证智能合约的 ABI
get_gas_price	获取当前 Gas 价格预言机数据（慢速／标准／快速，单位为 Gwei）

快速开始

1. 添加到你的 MCP 客户端

将以下内容添加到 MCP 客户端配置中（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "etherscan": {
      "command": "npx",
      "args": ["-y", "etherscan-mcp-server"]
    }
  }
}

就这样。npx 会自动下载并运行它。如需更高的速率限制，可在 etherscan.io/apis 获取免费 API 密钥并添加：

{
  "mcpServers": {
    "etherscan": {
      "command": "npx",
      "args": ["-y", "etherscan-mcp-server"],
      "env": {
        "ETHERSCAN_API_KEY": "your_key_here"
      }
    }
  }
}

2. 使用它

向 AI 助手提出类似以下问题：

• “vitalik.eth 地址 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 的 ETH 余额是多少？”
• “显示该地址的 ERC-20 代币余额”
• “获取交易 0x... 的详情”
• “列出该地址最近的 20 笔普通交易”
• “显示转入此钱包的所有 USDT 转账”
• “获取 USDC 合约 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 的 ABI”
• “Ethereum 主网上当前的 Gas 价格是多少？”

示例输出

get_eth_balance

ETH Balance for 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

247.3821 ETH

get_gas_price

⛽ Etherscan Gas Price Oracle

- Safe Low (🐢): 12.50 Gwei
- Standard (🚗): 15.20 Gwei
- Fast (🚀): 18.90 Gwei

- Last Block: 19850000
- Gas Used Ratio: 0.512
- Suggested Base Fee: 13.40 Gwei

*Estimated tx cost for 21,000 gas: 🐢 0.000263 ETH | 🚀 0.000397 ETH*

get_transactions_by_address

Normal Transactions for 0xd8dA...6045 (20 results, page 1)

- ✅ ↗ OUT 0.5 ETH · transfer — block 19,850,123 — 2026-06-05 — gas: 15.20 Gwei — hash: 0x4f8a2b9c3d1e5f7a...
- ✅ ↙ IN 1.2 ETH · transfer — block 19,849,876 — 2026-06-05 — gas: 14.80 Gwei — hash: 0x9c1d4e7f2a8b6c3d...
- ❌ ↗ OUT 0.0 ETH · swapExactTokensForETH — block 19,849,500 — 2026-06-05 — gas: 22.10 Gwei — hash: 0x2b7c9e1f4a3d8b5c...

get_contract_abi

Contract ABI for 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

- Functions: 28
- Events: 13
- Constructors: 1
- Fallback/Receive: 0

### Functions (showing first 25)
  - `name()` → string (view)
  - `symbol()` → string (view)
  - `decimals()` → uint8 (view)
  - `totalSupply()` → uint256 (view)
  - `balanceOf(address)` → uint256 (view)
  - `transfer(address,uint256)` → bool (nonpayable)
  - `approve(address,uint256)` → bool (nonpayable)
  - `transferFrom(address,address,uint256)` → bool (nonpayable)
  ...

使用场景

钱包检查

“检查此地址的 ETH 和代币余额” — 几秒钟内即可获取任意钱包持仓快照。适用于任何 Ethereum 地址，包括智能合约钱包和多签钱包。

交易取证

“显示此地址最近的 20 笔交易” — 追踪链上活动、识别交易对手并了解资金流向。合约调用可使用 get_internal_transactions，代币转账可使用 get_erc20_transfers。

智能合约分析

“获取 Uniswap Router 合约的 ABI”——获取已验证合约的 ABI，了解有哪些可用函数。对于调试失败的交易或了解协议的工作方式至关重要。

Gas 优化

“当前 Gas 价格是多少？”——获取慢速／标准／快速 Gas 估算及预估交易成本。选择合适的交易时机，节省费用。

DeFi 投资组合跟踪

“显示我钱包中的所有代币余额”——汇总 ERC-20 代币的持仓。与 CoinGecko MCP 服务中的 get_prices 结合使用，即可全面估算投资组合价值。

安全审计

“列出此合约的所有内部交易”——追踪内部调用，了解合约行为。可用于识别异常模式，或验证合约是否如其所述运行。

安全

• 无需 API 密钥——可使用 Etherscan 免费层级。可选 API 密钥可提高速率限制。
• 只读——仅从 Etherscan 的 API 获取公开区块链数据。不会写入或修改任何内容。
• 不访问本地文件——不会读取或写入你计算机上的任何文件。
• 不访问 Shell——不会执行命令或启动进程。
• 受速率限制——自动限制请求，以符合免费层级的限制。
• 开源——采用 MIT 许可证。可在 GitHub 查看代码。

故障排除

“需要 API 密钥”或响应非常缓慢

没有 API 密钥时，Etherscan 会将请求限制为每 5 秒 1 次。在 etherscan.io/apis 获取免费密钥，并设置 ETHERSCAN_API_KEY 环境变量，即可达到每秒 5 次调用。

“超出速率限制”（429）

服务会在收到 429 时自动重试，但快速连续查询仍可能触及限制。使用免费 API 密钥时，每秒可调用 5 次。为获得最佳效果，请将请求间隔设为约 200 毫秒。

“找不到合约”或 ABI 为空

只有经过验证的合约才会在 Etherscan 上提供 ABI。如果合约未经验证，API 会返回错误。请先在 etherscan.io 检查合约的验证状态。

服务无法启动

确保已安装 Node.js 18+：node --version。如果使用 npx，请确保 npm 为最新版本：npm install -g npm@latest。

MCP 客户端无法连接

确认配置路径正确。macOS 上的 Claude Desktop 使用 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上则使用 %APPDATA%\Claude\claude_desktop_config.json。更改配置后，请重启客户端。

“地址校验和”错误

Etherscan 要求地址带有校验和（大小写混合）。服务会自动处理，但如果仍然出现错误，请尝试使用 etherscan.io 上显示的校验和地址。

要求

• Node.js 18+
• Etherscan API 密钥（推荐）——在 etherscan.io/apis 获取免费密钥

速率限制

服务会自动将请求速率限制在每秒约 4 次，以符合 Etherscan 免费层级的限制（每秒 5 次）。没有 API 密钥时，Etherscan 会将请求限制为每 5 秒 1 次。

如需使用更高的限制，请注册免费的 Etherscan API 密钥，并设置 ETHERSCAN_API_KEY 环境变量：

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

开发

git clone https://github.com/nova/etherscan-mcp-server.git
cd etherscan-mcp-server
npm install
npm run build
npm start

许可证

MIT