Etherscan V2 MCP Server

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下运行，没有解析错误。

许可证 麻省理工学院