TONNode — TON blockchain access

@tonnode/mcp

Русская версия

为 AI Agent 提供直接访问 The Open Network (TON) liteserver 的 MCP 服务——中间无需 HTTP 网关。通过 TON 原生 ADNL 协议查询余额、账户状态、交易历史和合约 get-method。

由 TONNode 构建——提供私有 TON liteserver、归档节点、内存池流和 REST API（早期访问，按需申请）。

快速开始

将其添加到 Claude Desktop、Claude Code、ChatGPT、Cursor、Codex 或任何 MCP 客户端：

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

集成就这么简单。默认情况下，服务通过公共全局配置连接到 TON 主网。各客户端的现成配置以及以编程方式使用 Node.js 的示例，均位于 examples/ 中。

工具

**命名说明：**原生币于 2026 年 6 月从 Toncoin 更名为 GRAM；网络本身仍称为 TON。工具输出使用 *_gram 字段。

工具	功能	典型问题
get_balance	查询地址的 GRAM 余额	“EQ… 持有多少 GRAM？”
get_jetton_balance	查询 Jetton/代币余额（USDT 及任何 TEP-74 代币）	“这个钱包里有多少 USDT？”
get_jetton_info	查询代币元数据：名称、符号、小数位数、供应量	“这个 Jetton 的小数位数是多少？”
get_transactions	查询近期交易：金额、发送方、手续费	“我的付款到账了吗？”
get_account_state	查询状态、部署标志、最后一笔交易指针	“这个合约已部署吗？”
run_get_method	在合约上运行只读 get-method	“在这个主合约上调用 get_jetton_data”
parse_address	离线转换/验证 EQ…/UQ…/原始格式	“这两个地址相同吗？”
get_masterchain_info	查询主链头信息：seqno、分片、哈希	“网络（或我的端点）正常运行吗？”
get_swap_quote	通过 Omniston 获取确定的 DEX 兑换报价（GRAM ⇄ 任意 Jetton）	“现在 100 GRAM 能换多少 USDT？”
build_swap_tx	构建未签名、兼容 TonConnect 的兑换交易	“为我的钱包准备好这笔兑换交易，以便签名”
get_crosschain_quote	获取 TON → Ethereum/Arbitrum/Base/BNB/Polygon/Avalanche 的报价	“我的 TON USDT 能换到 Ethereum 上多少 USDT？”
build_crosschain_swap_tx	构建未签名的 HTLC 托管交易及其密钥	“开始这笔跨链兑换”
track_crosschain_swap	实时追踪两条链上的跨链交易阶段	“解析方已在 Ethereum 上锁定我的 USDT 了吗？”
disclose_crosschain_secret	揭示密钥——原子结算两边的交易	“完成兑换”
build_crosschain_refund	构建未签名的取消交易，取回托管资金	“交易卡住了——把我的钱退回来”
generate_wallet	创建全新的 TON 钱包（助记词 + 密钥 + 地址）	“为我的 Agent 创建一个钱包”

钱包生成

generate_wallet 会创建全新的钱包——包含一个 24 词助记词、对应的 ed25519 密钥对，以及所选合约版本对应的地址（默认 v4，还支持 v3r2、v5r1 和 highload_v3，后者用于批量付款）。v3r2/v4/v5r1 地址来自 @ton/ton 的规范合约；highload_v3 地址根据官方合约代码推导，并与维护中的参考实现交叉验证。

⚠️ 此操作会返回密钥材料。在托管模式下，密钥在服务端生成并通过 TLS 返回——请将每个生成的钱包都视为热钱包：适合程序化/临时用途，但应将有实际价值的余额转入冷存储，并避免将响应写入日志或共享对话记录。服务绝不会存储或记录助记词或私钥（只存储公开地址）。运营方可设置 TONNODE_DISABLE_WALLET_GEN=1 来完全移除此工具。

兑换 — 真正能够交易的 Agent

get_swap_quote 和 build_swap_tx 由 Omniston 提供支持。Omniston 是 STON.fi 的 RFQ 协议，可聚合 STON.fi 和 DeDust 的流动性。无需 API 密钥。

整个流程严格遵循非托管模式——服务端永远不会接触私钥、签名或广播交易：

1. get_swap_quote 锁定一份确定报价（金额以不可再分的原始单位表示；响应中包含滑点下限、价格影响、Gas 预算和 DEX 路由）。
2. build_swap_tx 将报价转换为未签名消息，其格式与 tonConnectUi.sendTransaction() 的要求完全一致——签名和发送仍由钱包所有者负责。

报价约一分钟后过期，因此请尽快构建。Omniston 会在构建时模拟转账：如果钱包中没有足够的输入金额，构建会提前失败，而不是在链上白白消耗 Gas。

跨链

*_crosschain_* 工具将同样的理念扩展到不同区块链：使用 GRAM 或任意 TON jetton 付款，在 Ethereum、Arbitrum、Base、BNB、Polygon 或 Avalanche 上收到 USDT/USDC/原生币——通过 Omniston 的原子 HTLC 托管进行结算，通常不到一分钟即可完成。TON 始终是源链（签名者是 TON 钱包）。

Agent 将驱动完整的原子交换生命周期：报价 → 构建（工具生成 HTLC 密钥并交给调用方——服务端不保留任何内容）→ 签名并发送 → 跟踪两条链 → 披露密钥以完成结算，或构建退款交易（如果交易停滞）。服务端、解析器或任何其他人都无法重定向资金：密钥只能按报价完成交易，而未完成的托管始终可由所有者的钱包收回。

托管式 / 自托管 HTTP 模式

该软件包还提供用于远程部署的 Streamable-HTTP 入口（mcp.tonnode.io 即由此驱动）：

TONNODE_KEYS=tn_live_abc,tn_live_def PORT=8808 npx -y @tonnode/mcp --http

想要现成的托管端点，而不是自行运行？mcp.tonnode.io 的密钥可通过 tonnode.io/mcp 获取。客户端无需安装任何内容即可连接：

{
  "mcpServers": {
    "ton": {
      "url": "https://your-host/mcp",
      "headers": { "Authorization": "Bearer tn_live_abc" }
    }
  }
}

请求通过 Bearer 密钥进行身份验证，并按密钥进行速率限制（RATE_LIMIT_RPM，默认值为 300）。除 Authorization: Bearer <key> 外，服务端还接受裸格式的 Authorization: <key> 和 X-API-Key: <key>——供将 Authorization 请求头保留给自身使用的网关（例如 Smithery）使用。密钥来自 TONNODE_KEYS（以逗号分隔的固定密钥）或 TONNODE_KEYS_FILE——这是一个 JSON 数组，格式为 {"key", "label"?, "rpm"?, "expires"?}，文件变更或收到 SIGHUP 时会热重载：无需重启即可添加或撤销客户密钥、设置每密钥速率限制，并为订阅计划设置自动过期密钥。被撤销密钥的活动会话会立即关闭。GLOBAL_RATE_LIMIT_RPM 会为所有密钥设置总上限，以保护后端 liteserver。会话仅对创建它的密钥可见；空闲会话会在 SESSION_TTL_MIN（默认 30 分钟）后清理，并且每个密钥和全局的并发会话数均有限制。未设置密钥时，服务端拒绝启动；设置 TONNODE_ALLOW_OPEN=1，即可明确选择在自有防火墙后无密钥运行。监控请使用 GET /healthz，密钥管理请使用 deploy/tonnode-keys.sh。

服务端默认绑定到 127.0.0.1——请在前方配置 TLS 反向代理（Caddy、nginx）；只有在代理运行于另一台机器时，才设置 HOST=0.0.0.0。现成的 systemd 和 Caddy 配置位于 deploy/。

配置

环境变量	含义
TON_LITESERVERS	使用自己的轻量服务器，而不是公共配置：[{"ip":"1.2.3.4","port":40004,"key":"<base64 ed25519>"}]
TON_CONFIG_URL	备用全局配置 URL
TON_NETWORK=testnet	使用测试网配置（或传入 --testnet）
TONNODE_KEYS	HTTP 模式：以逗号分隔的 Bearer API 密钥（简单、固定）
TONNODE_KEYS_FILE	HTTP 模式：包含标签、每个密钥的 rpm、expires 的 JSON 密钥文件 — 热重载
HOST	HTTP 模式：绑定地址（默认 127.0.0.1）
PORT	HTTP 模式：监听端口（默认 8808）
RATE_LIMIT_RPM	HTTP 模式：每个密钥每分钟的默认请求数（默认 300）
GLOBAL_RATE_LIMIT_RPM	HTTP 模式：所有密钥的总上限（默认关闭）
SESSION_TTL_MIN	HTTP 模式：会话闲置多少分钟后清理（默认 30）
MAX_SESSIONS / MAX_SESSIONS_PER_KEY	HTTP 模式：并发会话上限（默认 500 / 50）
OMNISTON_API_URL	兑换工具：备用 Omniston WebSocket 端点（默认 wss://omni-ws.ston.fi）
OMNISTON_INTEGRATOR_ADDRESS / OMNISTON_INTEGRATOR_FEE_BPS	兑换工具：可选的集成商收入分成，以输出金额的基点计 — 每个报价都会通过 integrator_fee_units 向调用方明确显示（默认关闭）
TONNODE_DISABLE_WALLET_GEN	设为 1 以移除 generate_wallet 工具（例如，在不希望服务器端生成密钥材料的共享托管端点上）

关于公共轻量服务器的说明

默认公共配置中的轻量服务器由多人共用，设有速率限制，且没有深层历史记录 — 对近期区块以外的 get_transactions 请求会返回 lt not in db。Agent 也常会突发查询，公共网关会对此限流。

如需自有速率限制和归档历史记录，请将 TON_LITESERVERS 指向私有轻量服务器 — 从控制台获取密钥对和 global.config.json，并使用由 GRAM 或 USDT 充值的余额付费。配置文件、ADNL 密钥和归档路由的工作方式详见 TON 轻量服务器指南。

内存池流

此 MCP 服务不会公开待处理消息 — 上述工具均不会读取内存池。TONNode 通过独立的 WebSocket 流 wss://mempool.tonnode.io/v1/stream 提供内存池数据：TONNode 的节点从公共覆盖网络收到外部消息时，每条消息都会以一个 JSON 对象的形式发送，此时消息尚未进入区块；支持按目标钱包、操作码或 DEX 池筛选，并在重新连接后提供短时回放。套餐价格取决于单个密钥上的并发连接数。覆盖范围并不完整 — 节点只能看到通过覆盖网络到达它的消息，不保证完整性或速度 — 而且通过 TONNode 轻量服务器发送的消息通常不会出现在其中（该节点不会发布自己的广播；在 2026 年 10 月 8 日的一次测试中，其他节点中继回来的副本仅出现在 20 次发送中的 2 次）。协议、密钥和套餐：tonnode.io/en/docs/mempool。

许可证

MIT © TONNode