blockchain-data-mcp

给 AI Agent 用的区块链数据 MCP server。只读查询，不签名不广播。 当前数据源：Tron（7 个工具）+ ETH（7 个工具）+ BSC（7 个工具）+ OKLink 地址标签（1 个工具）。

已实现工具

Tron（TronGrid API，无需浏览器）

• tron_get_account 账户信息：TRX 余额、TRC10/TRC20、能量带宽资源、质押
• tron_get_transaction 交易详情：区块、结果、手续费、能量消耗、合约调用、事件日志
• tron_get_block 区块信息，可按号或取最新
• tron_get_trc20_balance TRC20 余额（精确单一合约或全部持有）
• tron_get_transaction_history 交易历史（trc20/native），支持分页
• tron_get_contract_info 合约信息：名称、字节码、ABI
• tron_call_read_contract 只读合约调用（view/pure 方法）

Ethereum / BNB Smart Chain（JSON-RPC + 区块浏览器 API）

ETH 和 BSC 各提供以下 7 类工具，工具名前缀分别为 eth_ 和 bsc_：

• get_balance 原生代币余额
• get_transaction 交易详情
• get_block 区块详情
• get_erc20_balance ERC20/BEP20 余额
• call_read_contract 只读合约调用
• get_transaction_history 普通交易历史
• get_erc20_transfers ERC20/BEP20 转账历史

OKLink（地址标签，需 Playwright 浏览器）

• oklink_get_address_label 地址标签查询：地址类型（合约/地址）、标签列表（交易所/代币名）、风险标记
  • 数据来源：OKLink 区块链浏览器（oklink.com）
  • 实现：Playwright 无头浏览器打开地址页，拦截页面原生 API 响应 + DOM 提取
  • 签名算法已逆向还原（HMAC-SHA256，见 src/oklink/sign.ts）

使用 npm 安装（推荐）

无需克隆项目，MCP 客户端直接通过 npx 启动：

Codex（~/.codex/config.toml）

[mcp_servers.blockchain]
command = "npx"
args = ["-y", "blockchain-data-mcp"]

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "blockchain": {
      "command": "npx",
      "args": ["-y", "blockchain-data-mcp"]
    }
  }
}

OKLink 标签查询依赖 Chrome/Edge；没有系统浏览器时，执行：

npx playwright install chromium

从源码安装

1. 前置条件

• Node.js >= 18
• 系统已安装 Chrome 或 Edge（OKLink 工具需要浏览器）
  • 如果没有系统 Chrome/Edge，执行 npx playwright install chromium 下载内置浏览器

2. 克隆并构建

git clone <repo-url> blockchain-data-mcp
cd blockchain-data-mcp
npm install
npm run build

3. 验证构建

npm run smoke

应输出 46/46 通过。

4. 接入 MCP 客户端

Codex（~/.codex/config.toml）

[mcp_servers.blockchain]
command = "node"
args = ["/绝对路径/blockchain-mcp/dist/index.js"]

可选环境变量：

[mcp_servers.blockchain]
command = "node"
args = ["/绝对路径/blockchain-mcp/dist/index.js"]
env = { TRONGRID_API_KEY = "你的key", OKLINK_BROWSER_PATH = "自定义浏览器路径" }

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "blockchain": {
      "command": "node",
      "args": ["/绝对路径/blockchain-mcp/dist/index.js"]
    }
  }
}

Cursor（Settings → MCP）

添加新 MCP Server:
- Type: stdio
- Command: node
- Args: /绝对路径/blockchain-mcp/dist/index.js

5. 环境变量（可选）

| 变量 | 作用 | 默认 | |------|------|------| | TRONGRID_API_KEY | TronGrid API key，提升速率配额 | 无（用公共端点） | | TRONGRID_BASE_URL | 自定义 TronGrid 端点 | https://api.trongrid.io | | ETH_RPC_URL | 自定义 Ethereum JSON-RPC 端点 | ethereum-rpc.publicnode.com | | BSC_RPC_URL | 自定义 BSC JSON-RPC 端点 | bsc-dataseed.bnbchain.org | | ETH_EXPLORER_API_KEY | Etherscan API key，用于历史记录查询 | 无 | | BSC_EXPLORER_API_KEY | BscScan API key，用于历史记录查询 | 无 | | OKLINK_BROWSER_PATH | 指定浏览器可执行文件路径 | 自动探测（Chrome/Edge/cloakbrowser） |

浏览器路径自动探测

OKLink 工具依赖浏览器，按以下优先级自动探测：

1. OKLINK_BROWSER_PATH 环境变量（最高优先级）
2. cloakbrowser（开发环境）
3. Windows Chrome（Program Files / Program Files (x86)）
4. Windows Edge
5. macOS Chrome（/Applications/Google Chrome.app）
6. Linux chromium（/usr/bin/chromium-browser）

探测不到时，回退到 Playwright 内置 chromium（需先执行 npx playwright install chromium）。

测试

npm test           # 真实节点冒烟测试（Tron + ETH + BSC + OKLink）
npm run smoke      # 与 npm test 相同

架构：增量集成新数据源

每个数据源是独立模块，导出 register(server, client)。加新源只需：

1. src/新源/ 下实现 client + tools
2. src/index.ts 追加一行注册

现有数据源互不依赖，退避限流按源独立封装。

src/
  index.ts          # 入口：聚合注册
  tron/             # Tron 数据源（TronGrid HTTP API）
    client.ts
    tools.ts
    address.ts
    units.ts
  evm/              # ETH/BSC 共用 JSON-RPC 与区块浏览器客户端
    client.ts
    tools.ts
    address.ts
    units.ts
  oklink/           # OKLink 数据源（Playwright 浏览器）
    sign.ts         # 签名算法（HMAC-SHA256，纯 Node）
    client.ts       # Playwright 客户端
    tools.ts        # MCP 工具注册
  utils/
    http.ts         # fetch + 退避重试