使用说明
Etherscan V2 MCP服务器
概述 Etherscan V2 MCP服务器公开了一组精心策划的Etherscan V2端点作为模型上下文协议（MCP）工具。它既可以作为可流式传输的HTTP MCP端点运行，也可以作为stdio MCP服务器运行。在整个项目中使用本地ESM。
关键文件：
- 服务器:
src/index.ts - 工具:
src/tools.ts - 模式:
src/schemas.ts - MCP资源:
src/resources.ts
需求
- Node.js：20+（建议22+）
- 包管理器：npm、yarn或pnpm
安装
npm i
环境
复制 .env.example 向 .env 并设定值：
- 以太网扫描_ PI_键：您的Etherscan（或支持的资源管理器）API密钥。
- ETHERSCAN_PRO软件：可选，启用专业功能（如果可用）。
- OPENAI_API密钥：可选，启用简单的NL路由
ethv2_nl_query. - REDIS_HOST, REDIS_PORT, REDIS_密码：可选；如果设置，服务器将使用Redis支持的缓存；否则在内存缓存中。
- 端口：默认值5009。
- 主机：默认值为0.0.0.0。
脚本
- 构建:
tsc - 开发:
tsx src/index.ts - 开始:
node dist/index.js - 测试:
jest --passWithNoTests
运行（HTTP MCP和REST信息）
# Development (tsx)
npm run dev
# Production build
npm run build && npm start
# Stdio mode for MCP-aware clients
node dist/index.js --stdio
HTTP端点（非MCP）
- 获取
/health：基本活性有效载荷。 - 获取
/api/tools：返回带有输入JSON模式的工具目录。 /mcp：MCP的流式HTTP传输。首先用POST初始化会话；坚持mcp-session-id同一会话中后续请求的标头。
MCP资源 这些可以通过MCP请求（而不是纯REST）发现：
etherscanv2://guide：关于选择工具和分页策略的Markdown指南。etherscanv2://api-map：类别的JSON映射➜ 工具名称。
缓存
每个工具都会缓存具有较小TTL的响应（例如，典型的5-300s，静态元数据的响应时间更长）。如果 REDIS_HOST 设置，使用Redis；否则，将使用内存中的回退缓存。看 src/tools.ts 对于每个工具应用的TTL。
惯例
- 始终包括
chainid（EVM链ID，例如1/以太坊，10/乐观主义，42161/Arbitrum，8453/Base）。 - 使用 分页 对于列表端点：
page和offset。不要在一次调用中聚合多个页面。 - 对于日志，使用地址/主题过滤器和
fromBlock/toBlock窗户。
工具目录
下面是工具名称、用途和简洁的输入模式（请参见 src/schemas.ts 权威定义）。
账户
- ethv2_帐户平衡 –在标签处获取账户余额。
- 输入：
{ chainid: number, address: string, tag?: 'latest'|'earliest'|'pending' }
- 输入：
- ethv2_account_txlist –地址的正常tx（分页）。
- 输入：
{ chainid, address, startblock?, endblock?, sort?: 'asc'|'desc', page?, offset? }
- 输入：
- ethv2_account_txlist内部 –地址的内部tx（分页）。
- 输入：与
ethv2_account_txlist
- 输入：与
- ethv2_account_tokentx –地址的ERC-20传输（分页；可选合约过滤器）。
- 输入：
{ chainid, address, contractaddress?, sort?, page?, offset? }
- 输入：
区块和交易
- ethv2_block_by_time –最接近时间戳的块编号。
- 输入：
{ chainid, timestamp: number, closest?: 'before'|'after' }
- 输入：
- ethv2_tx_receipt_status –tx哈希的收据状态。
- 输入：
{ chainid, txhash: string }
- 输入：
- ethv2_tx_status –tx哈希的交易状态。
- 输入：
{ chainid, txhash: string }
- 输入：
合同
- ethv2-contract_getabi –已验证的ABI合同。
- 输入：
{ chainid, address }
- 输入：
- ethv2_合同_电源代码 –已验证的合同源代码。
- 输入：
{ chainid, address }
- 输入：
日志
- ethv2_logs_getLogs –按地址/主题记录日志（分页；带窗口）。
- 输入：
{ chainid, address?, fromBlock?, toBlock?, topic0?, topic1?, topic2?, topic3?, page?, offset? }
- 输入：
代币
- ethv2_token_供应 –通过合同提供代币。
- 输入：
{ chainid, contractaddress }
- 输入：
- ethv2_token_balance –地址的令牌余额。
- 输入：
{ chainid, contractaddress, address, tag?: 'latest'|'earliest'|'pending' }
- 输入：
- ethv2_token_holdlist –令牌的持有者列表（分页）。
- 输入：
{ chainid, contractaddress, page?, offset? }
- 输入：
- ethv2_account_tokennfttx –ERC‑721地址传输（分页；可选合约筛选器）。
- 输入：
{ chainid, address, contractaddress?, sort?, page?, offset? }
- 输入：
- ethv2_account_token155tx –ERC‑1155地址传输（分页；可选合约筛选器）。
- 输入：
{ chainid, address, contractaddress?, sort?, page?, offset? }
- 输入：
天然气与统计
- ethv2-gas_oracle –每条链的气体预言机（基础/快速/安全）。
- 输入：
{ chainid }
- 输入：
- ethv2_stats_ethprice –每条链的ETH价格。
- 输入：
{ chainid }
- 输入：
- ethv2_stats_ethsupply –每条链的ETH供应。
- 输入：
{ chainid }
- 输入：
Proxy (JSON‑RPC)
- ethv2_proxy_blockNumber –
eth_blockNumber.- 输入：
{ chainid }
- 输入：
- ethv2_proxy_getBlockByNumber –
eth_getBlockByNumber.- 输入：
{ chainid, tag: string /* hex or 'latest' */, boolean?: boolean /* include tx objects */ }
- 输入：
- ethv2_proxy_getTransactionByHash –
eth_getTransactionByHash.- 输入：
{ chainid, txhash }
- 输入：
姓名标签
- ethv2_nametag_by_address –地址名称标签（如果支持）。
- 输入：
{ chainid, address }
- 输入：
自然语言（可选）
- ethv2_nl查询 –轻量级NL路由器，用于常见目的。
- 输入：
{ chainid: number, query: string } - 注意：查找简单的意图，如gas、tx状态、余额、日志；否则返回指导。
- 输入：
例子 列出工具（REST）：
curl http://localhost:5009/api/tools | jq
通过MCP获取gas oracle（stdio示例 node --stdio 需要MCP客户端）。对于简单的HTTP健全性检查，您可以从一次性脚本快速调用底层客户端，也可以使用定制的MCP客户端。
ESM注释
该项目为原生ESM("type": "module").本地进口包括明确 .js 源代码中的扩展，以便在 dist/ 在节点ESM下运行，没有解析错误。
许可证 麻省理工学院
