TON MCP 接入教程：把 Claude 和 Cursor 连上 TON，一步步来

凡是试过让 AI 智能体在 TON 上干点活的人，都撞过这堵墙。你让 Claude 查个钱包余额——它老老实实承认自己连不上网络，或者更糟：凭空编一个 jetton 地址，把 nanoton 和 TON 搞混，数字全靠脑补。给它一条指向公共 API 的 curl——负载一上来就收到 HTTP 429 Too Many Requests，而没有密钥时限额大约是每秒一个请求。全局配置里的公共 lite server 一会儿返回 not ready，一会儿直接 ADNL 超时掉线。问题不在模型身上——智能体只是没有一双能摸到区块链的手。MCP 给它的正是这双手。

下面几分钟内搞定：把 Claude 接入 TON，顺便配好 Cursor TON MCP、Claude Code 和 Codex——精确到每一行的配置、免费的 npx 启动方式，以及撞到限额之后如何切到 hosted 密钥。

MCP 是什么，智能体操作 TON 为什么离不开它

MCP（Model Context Protocol）是一个开放标准，规定了 AI 智能体如何调用外部工具。可以类比 USB：以前每个设备都有自己的接口，现在一个端口通吃。MCP 就是智能体与外部世界之间的“统一接口”。Claude Desktop、Claude Code、Cursor、ChatGPT/Codex 以及任何其他 MCP 客户端说的都是同一种语言：客户端连上 MCP 服务器，拿到工具列表，然后按模型的要求去调用。

要让智能体能访问 TON 网络，就需要一个会干这件事的 MCP 服务器。我们用 TONNode——面向 TON 的 hosted MCP 服务器。它给智能体提供整整 16 个工具：链上读取（余额、账户状态、交易、合约 get 方法、jetton 余额和元数据）、通过 DEX 协议 Omniston 做兑换、基于原子 HTLC 托管的跨链兑换，以及钱包生成。兑换、跨链和钱包相关的工具严格非托管：服务器从不签名交易、从不保管私钥——它只返回未签名的 TonConnect 消息，由用户自己的钱包完成签名。

对这篇教程来说，验证连通性只需要四个读取工具：

• get_masterchain_info——主链链头（确认服务器活着的最快方式）；
• get_balance——按地址查 GRAM 余额；
• get_jetton_balance——jetton 余额（USDT 等），jetton 钱包地址在链上实时计算；
• parse_address——EQ/UQ/raw 地址的转换与校验，完全离线。

把 Claude 接入 TON：npx 快速上手（一条命令）

什么都不用安装。一条命令拉起本地服务器：

npx -y @tonnode/mcp

@tonnode/mcp 这个包是开源的（MIT），发布在 npm 和 GitHub（tonnode/mcp）上，走 TON 原生的 ADNL 协议，中间没有任何 HTTP 中转层。公共配置免费提供全套读取工具——足够智能体查余额、查交易、查账户状态、调 get 方法了。

之后要往各个客户端里粘贴的基础配置长这样：

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

记住这个 mcpServers 结构——它在几乎所有客户端里都原样复用，下面无非是逐个说明该把它放到哪里。免费模式的详细拆解见另一篇指南免费用上 TON 的 MCP。

不想在本地装？ 登录后立刻就能领到 hosted 端点的免费 Hobby 密钥，无需绑卡——去 tonnode.io/dashboard 领取，然后直接填进下面的配置。

Claude Desktop：claude_desktop_config.json 在哪儿，往里写什么

Claude Desktop 从 claude_desktop_config.json 文件读取 MCP 配置。路径因系统而异：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

打开这个文件（没有就新建一个），写入那个 mcpServers 对象：

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

改完之后重启应用——Claude Desktop 只在启动时加载配置。工具菜单里会出现名为 ton 的服务器。现在在聊天框里输入：

调用 get_masterchain_info，告诉我主链链头的 seqno。

如果智能体返回了区块号——MCP 就接通了。同样可以让它“查一下钱包 UQ… 的余额”——底层会触发 get_balance，返回以 GRAM 计的真实数字（GRAM 是 2026 年 6 月更名后的 Toncoin；网络本身仍然叫 TON）。

Claude Code：claude mcp add 命令与 .mcp.json 文件

在 Claude Code 里，终端一条命令即可添加服务器——它会自动把所有内容写进对应的文件。本地版本：

claude mcp add ton -- npx -y @tonnode/mcp

双横线 -- 把服务器的启动命令与 claude 自身的参数分隔开。执行后 Claude Code 会创建（或补充）项目级的 .mcp.json。愿意的话也可以手动把同一个 mcpServers 对象写进文件——效果完全一样：

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

直接在 CLI 里验证连通性：

用 parse_address 把 0:83df... 转成 user-friendly 的 EQ/UQ 格式。

parse_address 完全离线工作，所以这是最可靠的测试：它不依赖网络状态，能立刻证明智能体已经看到了这些工具。

Cursor：.cursor/mcp.json 文件（项目级与全局）

对已经配好 Claude Desktop 的人有个好消息：Cursor 用的是一模一样的 mcpServers 格式。配置原样照抄即可——一个字都不用改。区别只在文件的位置：

• 项目根目录下的 .cursor/mcp.json——服务器只在这个项目里可见；
• ~/.cursor/mcp.json——全局，所有项目通用。

冲突时项目级文件优先。往里放：

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

这就是全部的 Cursor TON MCP 配置：一个文件，真正起作用的就四行。保存后到 Settings → MCP 里确认 ton 处于 Enabled 状态，然后直接在编辑器里问智能体：

钱包 EQ... 上有多少 USDT？调用 get_jetton_balance。

get_jetton_balance 会自动在链上算出 jetton 钱包地址——不需要你手动推导。关于如何一次调用拿到 USDT 余额，有单独一篇拆解。

Codex CLI：config.toml 与 codex mcp add 命令

Codex 是个例外：它的配置是 TOML 而不是 JSON，位于 ~/.codex/config.toml。结构不同，但意思一样。本地服务器最简单的添加方式是一条命令：

codex mcp add ton -- npx -y @tonnode/mcp

写在文件里长这样：

[mcp_servers.ton]
command = "npx"
args = ["-y", "@tonnode/mcp"]

hosted 端点在 Codex 里只能通过 config.toml 配置——带 url 和 Authorization 请求头的现成配置块在下面讲 hosted 密钥的章节里。如果你手动改 TOML，记住这里的语法不是花括号而是方括号里的 section，所以不能把 Cursor 的 JSON 机械地照搬过来。添加完成后启动 codex，让它调用 get_masterchain_info——返回 seqno 就说明接通了。

什么时候该切到 mcp.tonnode.io 的 hosted 密钥，以及怎么填

本地的 npx 服务器很适合上手试玩和搭原型。但它有天花板：它走的是全局配置里的 TON 公共 lite server。这些服务器是共享且限流的——负载一高就频繁返回 not ready 或 ADNL 超时，也不保存深度历史。一旦智能体开始正经干活——服务用户、循环轮询余额、连续调几十个 get 方法——你就会撞上这些限制。

差距在一个简单场景里就能看出来。假设智能体每分钟遍历一份五十来个钱包的清单，每个钱包都调一次 get_balance 加一次 get_jetton_balance——一轮下来就是上百次调用。在公共配置上，这样的循环几乎必然撞上大约每秒一个请求的限额：一部分地址返回 not ready，一部分超时掉线，智能体只好重试，把共享的 lite server 压得更狠。而在带专属密钥的 hosted 端点上，同样的一百次调用稳稳落在分配给你的吞吐额度内，历史和账户状态也能稳定返回，不用跟别人抢公共资源。

这时就该切到 hosted 端点 mcp.tonnode.io，用自己的密钥和有保障的吞吐量。形如 tn_live_… 的密钥是访问 https://mcp.tonnode.io/mcp 的 Bearer 令牌。hosted 配置的区别在传输方式：不再启动本地进程，而是指定 HTTP 和授权请求头：

{
  "mcpServers": {
    "ton": {
      "type": "http",
      "url": "https://mcp.tonnode.io/mcp",
      "headers": {
        "Authorization": "Bearer tn_live_…"
      }
    }
  }
}

Claude Code 有对应的命令——注意各个 flag 要放在服务器名之前：

claude mcp add --transport http ton https://mcp.tonnode.io/mcp \
  --header "Authorization: Bearer tn_live_…"

Codex 的 hosted 端点写在 ~/.codex/config.toml 里——授权请求头单独一个 section：

[mcp_servers.ton]
url = "https://mcp.tonnode.io/mcp"

[mcp_servers.ton.headers]
Authorization = "Bearer tn_live_…"

关于定价诚实度的重要一点：全部 16 个工具在所有套餐上都可用，包括免费的 Hobby。密钥只决定吞吐量，不决定工具集。没有任何“订阅解锁高级功能”的套路——你付的钱只买请求通行量：

• Hobby——永久免费，60 请求/分钟；
• Pro——$29/月，300 请求/分钟；
• Scale——$199/月，1200 请求/分钟。

免费的 Hobby 密钥登录仪表盘后立刻发放，无需绑卡。也就是说，只要 60 请求/分钟够用，从本地模式切到 hosted 一分钱都不用花——而它已经比公共 lite server 可靠得多。

服务器没出现怎么办

MCP 接入很少坏得很复杂——几乎总是栽在三件小事之一：

• 工具列表里看不到服务器。客户端只在启动时读配置，所以改完文件后要彻底重启 Claude Desktop、Cursor，或重开 Codex 会话。Claude Code 里用 claude mcp list 命令检查状态。
• 服务器一启动就崩。通常是 node/npx 不在 PATH 里——npx -y @tonnode/mcp 这条命令在普通终端里应当能无报错启动。如果终端里能跑、客户端里不行，就在配置的 command 字段里写上 npx 的绝对路径。
• 读取工具返回 not ready 或超时。这不是你的配置有问题，而是公共 lite server 过载了。重试即可；如果在负载下反复出现，就切到 hosted 密钥——那边是专属吞吐量，不用排公共队列。

另外记得校验 JSON 和 TOML 的合法性：mcpServers 里多打一个逗号、config.toml 里括号写错，是客户端一声不吭忽略服务器的最常见原因。

小练习：你会最先调用的那些工具

不管用哪个客户端，最终验证都一样——发一个简单的读取调用。以下是典型提示词和背后的工具：

• “主链现在的 seqno 是多少？” → get_masterchain_info。网络的链头，确认 MCP 还活着的最佳方式。
• “钱包 UQ… 上有多少 GRAM？” → get_balance。原生币余额。
• “这个地址上有多少 USDT？” → get_jetton_balance。jetton 钱包地址在链上实时计算，不需要提前知道。
• “把地址 EQ… 转成 UQ 格式” → parse_address。离线转换与格式校验。

接下来就可以给智能体派真正的活了：

• “对这个地址调 get_account_state，告诉我合约是否已部署、最后一笔交易是什么时候。”
• “通过 run_get_method 调用 jetton 钱包的 get_wallet_data，把返回值解析一下。”不装 SDK 怎么调只读 get 方法，见不用 SDK 调用 get 方法这篇拆解。
• “这个 jetton 有几位小数？调用 get_jetton_info。”（USDT 是 6 位，大多数 jetton 是 9 位；decimals 是把 raw 单位换算成正确数值的关键。）

TON 的 MCP 全部能力总览，收录在这篇大指南里。

总结

把智能体接入 TON，说白了就是往客户端配置里写四行 JSON（或者敲一条命令）。本地的 npx -y @tonnode/mcp 免安装、免密钥，读取工具全套齐活。等撞上公共 lite server 的限额——把传输方式切到 hosted 端点 mcp.tonnode.io、填上 tn_live_… 即可，智能体逻辑一行都不用动。

花一分钟领个免费 Hobby 密钥填进配置 → tonnode.io/dashboard?plan=hobby。不需要绑卡，16 个工具全套立即可用。想先看看服务器到底能干什么——去工具页面逛一圈。