内容
# @tonnode/mcp
[俄语版本](README.ru.md)
MCP 服务器，为 AI 代理提供直接 **liteserver** 访问 [The Open Network (TON)](https://ton.org) 的能力 —— 无需中间的 HTTP 网关。余额、账户状态、交易历史和合约的 get 方法均通过 TON 的原生 ADNL 协议提供。
由 [TONNode](https://tonnode.io) 构建 —— 私有 TON liteservers、存档节点、内存池流和索引 API。
## 快速开始
在 Claude Desktop、Claude Code、ChatGPT、Cursor、Codex 或任何 MCP 客户端中添加：
```json
{
"mcpServers": {
"ton": {
"command": "npx",
"args": ["-y", "@tonnode/mcp"]
}
}
}
```
这就是整个集成过程。服务器默认通过公共全局配置连接到 TON 主网。所有客户端的预制配置以及以 Node.js 编程方式使用的方法都在 [examples/](examples/) 中。
## 工具
> **命名说明：** 原生代币从 Toncoin 在 2026 年 6 月更名为 **GRAM**；网络本身仍称为 **TON**。工具输出使用 `*_gram` 字段。
| 工具 | 功能 |
|---|---|
| `get_masterchain_info` | 当前主链头部：序列号、分片、区块哈希 |
| `get_balance` | 地址的 GRAM 余额（GRAM + nano） |
| `get_account_state` | 状态（活跃/冻结/未初始化）、余额、最后的交易指针、代码/数据标志 |
| `get_transactions` | 最近的交易：lt、时间、入金价值、手续费 |
| `run_get_method` | 合约上的只读 get 方法（`seqno`、`get_wallet_address` 等） |
## 主机/自托管 HTTP 模式
软件包还附带了一个 Streamable-HTTP 入口，用于远程部署（这就是 `mcp.tonnode.io` 的工作原理）：
```bash
TONNODE_KEYS=tn_live_abc,tn_live_def PORT=8808 npx -y @tonnode/mcp --http
```
客户端无需安装任何东西即可连接：
```json
{
"mcpServers": {
"ton": {
"url": "https://your-host/mcp",
"headers": { "Authorization": "Bearer tn_live_abc" }
}
}
}
```
请求使用 `TONNODE_KEYS`（逗号分隔）的 Bearer 密钥进行身份验证，并且每个密钥都有速率限制（`RATE_LIMIT_RPM`，默认为 300）。会话对于打开它们的密钥是私有的，空闲会话在 `SESSION_TTL_MIN`（默认为 30 分钟）后被清除，并对每个密钥和全局并发会话进行限制。如果没有 `TONNODE_KEYS`，服务器将拒绝启动；设置 `TONNODE_ALLOW_OPEN=1` 以在自己的防火墙后面明确运行无密钥的服务器。`GET /healthz` 用于监控。
服务器默认绑定 `127.0.0.1` —— 在前面放置 TLS 反向代理（Caddy、nginx）并设置 `HOST=0.0.0.0`，前提是代理在另一台机器上运行。预制的 systemd + Caddy 配置文件位于 [`deploy/`](deploy/) 中。
## 配置
| 环境变量 | 含义 |
|---|---|
| `TON_LITESERVERS` | 使用您自己的 liteservers 代替公共配置：`[{"ip":"1.2.3.4","port":40004,"key":"<base64 ed25519>"}]` |
| `TON_CONFIG_URL` | 替代的全局配置 URL |
| `TON_NETWORK=testnet` | 使用测试网配置（或传递 `--testnet`） |
| `TONNODE_KEYS` | HTTP 模式：逗号分隔的 Bearer API 密钥 |
| `HOST` | HTTP 模式：绑定地址（默认为 `127.0.0.1`） |
| `PORT` | HTTP 模式：监听端口（默认为 8808） |
| `RATE_LIMIT_RPM` | HTTP 模式：每分钟每个密钥的请求数（默认为 300） |
| `SESSION_TTL_MIN` | HTTP 模式：会话空闲多少分钟后被清除（默认为 30） |
| `MAX_SESSIONS` / `MAX_SESSIONS_PER_KEY` | HTTP 模式：并发会话限制（默认为 500 / 50） |
### 关于公共 liteservers 的说明
默认的公共配置 liteservers 是共享的、有限速的，并且 **没有深历史记录** —— `get_transactions` 超出近期区块将返回 `lt not in db`。代理也倾向于突发性查询，公共网关会对这种情况进行限制。
为了保证吞吐量、存档深度和节点级内存池流，请将 `TON_LITESERVERS` 指向私有端点 —— [tonnode.io](https://tonnode.io) 在一分钟内即可提供，付款方式为 TON。
## 许可证
MIT © [TONNode](https://tonnode.io)
MCP 市场