mcp

用途

TON MCP 服务器为 AI 代理提供对 The Open Network（TON）liteserver 的直接访问，无需中间 HTTP 网关。它让 Claude、ChatGPT、Cursor、Codex 以及任何 MCP 客户端能够通过 TON 原生 ADNL 协议查询链上数据，包括 GRAM 余额、账户状态、交易历史以及合约 get-methods。

该服务器由 TONNode 构建，TONNode 还提供私有 TON liteserver、归档节点、mempool 流和 REST API（早期访问，按需申请）。

主要能力

• 链上查询：通过原生 ADNL 协议访问 liteserver，查询 GRAM 余额、账户状态、交易历史和合约 get-methods。支持私有与归档端点。
• 钱包生成：generate_wallet 工具可生成新钱包，包含 24 词助记词、ed25519 密钥对以及所选合约版本的地址（默认 v4，另支持 v3r2、v5r1 和用于批量支付的 highload_v3）。v3r2/v4/v5r1 地址来自 @ton/ton 的标准合约；highload_v3 从官方合约代码派生，并与维护的参考实现交叉核对。
• 兑换（Swap）：get_swap_quote 和 build_swap_tx 由 Omniston 提供支持，Omniston 是 STON.fi 的 RFQ 协议，聚合 STON.fi 与 DeDust 的流动性，无需 API 密钥。
• 跨链兑换：*_crosschain_* 工具支持跨链支付与兑换，可使用 GRAM 或任意 TON jetton 支付，在 Ethereum、Arbitrum、Base、BNB、Polygon 或 Avalanche 上接收 USDT/USDC/原生币，通过 Omniston 的原子 HTLC 托管结算，通常在一分钟内完成。TON 始终是源链（签名者为 TON 钱包）。

使用方式

添加到 MCP 客户端：可添加到 Claude Desktop、Claude Code、ChatGPT、Cursor、Codex 或任何 MCP 客户端。服务器默认通过公共全局配置连接 TON 主网。每个客户端的现成配置以及 Node.js 编程用法位于 examples/ 目录中。

兑换流程：严格非托管，服务器从不查看私钥、从不签名、从不广播。get_swap_quote 锁定一个固定报价（金额以原始不可分割单位计；应答包含滑点下限、价格影响、gas 预算和 DEX 路由）。build_swap_tx 将报价转换为 tonConnectUi.sendTransaction() 所需形状的未签名消息——签名和发送仍由钱包所有者完成。报价约一分钟后过期，需及时构建。Omniston 在构建时会模拟转账：如果钱包不持有输入金额，构建会提前失败，而不是在链上燃烧 gas。

跨链原子交换生命周期：报价 → 构建（工具生成 HTLC 秘密并交给调用方——服务器不保留任何内容）→ 签名并发送 → 追踪两条链 → 披露秘密以结算，或在交易停滞时构建退款。

托管/自托管 HTTP 模式：该包还附带用于远程部署的 Streamable-HTTP 入口（即 mcp.tonnode.io 背后的实现）。可选择使用现成的托管端点，密钥在 tonnode.io/mcp 发放，客户端无需安装任何东西即可连接。请求通过 Bearer 密钥认证并按密钥限流（RATE_LIMIT_RPM，默认 300）。除 Authorization: Bearer <key> 外，服务器还接受裸 Authorization: <key> 和 X-API-Key: <key>。密钥来自 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/。

适用场景

• AI 代理需要查询 TON 链上数据（余额、账户状态、交易历史、合约 get-methods）。
• 程序化或临时性使用场景下的钱包生成。
• 代理驱动的 TON 代币兑换与跨链兑换。
• 需要私有 liteserver 或归档历史以避免公共端点限流的场景。

限制与注意事项

• 钱包安全：generate_wallet 返回秘密密钥材料。在托pipe模式下密钥在服务器生成并通过 TLS 返回——应将每个生成的钱包视为热钱包：适合程序化/临时使用，但任何有意义的余额应转移到冷存储，并确保响应不出现在日志和共享记录中。服务器从不存储或记录助记词或私钥（仅公开地址）。操作者可通过 TONNODE_DISABLE_WALLET_GEN=1 完全移除该工具。
• 公共 liteserver：默认的公共配置 liteserver 是共享的、有限流的，且不保留深层历史——get_transactions 超出近期区块将回答 lt not in db。代理也倾向于突发查询，公共网关会限流。如需自有速率限制和归档历史，可将 TON_LITESERVERS 指向私有 liteserver——从控制台获取密钥对和 global.config.json，并用以 GRAM 或 USDT 资助的余额付费。
• Mempool：待处理消息不通过此 MCP 服务器暴露——上述工具均不读取 mempool。TONNode 将 mempool 作为单独的 WebSocket 流提供：wss://mempool.tonnode.io/v1/stream，每条外部消息一个 JSON 对象，支持按目标钱包、op code 或 DEX 池过滤，重连后有短暂重放。计划按单密钥的并发连接数定价。覆盖范围是部分的——节点仅看到通过 overlay 到达它的内容，不承诺完整性或速度数据——通过 TONNode liteserver 发送的消息通常不会出现在其中（节点不发布自己的广播；在 2026 年 10 月 8 日的一次测试中，20 次发送中有 2 次出现了其他节点中继回来的副本）。协议、密钥和计划：tonnode.io/en/docs/mempool。

命名说明

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