用途
ton-cli 是 TON 项目中一个允许用户直接从命令行调用 TON 钱包 MCP 工具的工具。它适合需要在终端或脚本中查询与操作 TON 钱包数据的场景。
调用模式
| 命令 |
说明 |
| npx @ton/mcp@alpha |
stdio MCP 服务器（用于 Claude Desktop / MCP 客户端） |
| npx @ton/mcp@alpha --http [port] |
HTTP MCP 服务器 |
| npx @ton/mcp@alpha <tool_name> [--arg value ...] |
原生 CLI：调用一个工具后退出 |
在同一个工作流中只能使用一种模式：要么是 MCP 服务器模式（stdio/--http），要么是原生 CLI。不要在同一任务或会话中混用。
原生 CLI 用法
# 无参数
npx @ton/mcp@alpha get_balance
# 命名参数（--key value）
npx @ton/mcp@alpha get_transactions --limit 5
npx @ton/mcp@alpha get_jetton_balance --jettonAddress EQAbc...
所有值以纯字符串形式传入；也接受 JSON 对象或数组。参数以 --key value 成对传入。对象或数组（{...} / [...]）会被 JSON 解析，其余内容保持为纯字符串。
输出
所有工具将 JSON 打印到 stdout。错误打印到 stderr，进程以退出码 1 退出。
BALANCE=$(npx @ton/mcp@alpha get_balance)
echo $BALANCE | jq '.balance'
环境变量
CLI 遵循与服务器相同的环境变量：
| 变量 |
说明 |
| NETWORK |
mainnet（默认）或 testnet |
| MNEMONIC |
单钱包模式下的 24 词助记词 |
| PRIVATE_KEY |
十六进制编码的私钥（助记词的替代方案） |
| WALLET_VERSION |
v5r1（默认）、v4r2 或 agentic |
| TONCENTER_API_KEY |
可选的 Toncenter API key |
| TON_CONFIG_PATH |
配置文件路径（默认：~/.config/ton/config.json） |
如果没有 MNEMONIC 或 PRIVATE_KEY，CLI 会使用位于 ~/.config/ton/config.json 的本地配置注册表（注册表模式）。在注册表模式下，钱包范围的工具可接受可选的 --walletSelector，按 id、名称或地址指定特定钱包。
工具参考
钱包与余额
| 工具 |
必需参数 |
可选参数 |
| get_wallet |
— |
--walletSelector |
| get_balance |
— |
--walletSelector |
| get_balance_by_address |
--address |
--walletSelector |
| get_jetton_balance |
--jettonAddress |
--walletSelector |
| get_jettons |
— |
--walletSelector |
| get_jettons_by_address |
--address |
--limit, --offset, --walletSelector |
| get_jetton_info |
--jettonAddress |
--walletSelector |
| get_transactions |
— |
--limit, --walletSelector |
| get_transaction_status |
--normalizedHash |
--walletSelector |
| get_known_jettons |
— |
— |
钱包注册表（仅配置注册表模式）
| 工具 |
必需参数 |
可选参数 |
| list_wallets |
— |
— |
| get_current_wallet |
— |
— |
| set_active_wallet |
--walletSelector |
— |
| remove_wallet |
--walletSelector |
— |
转账
| 工具 |
必需参数 |
可选参数 |
| build_ton_transfer |
--toAddress, --amount |
--comment, --walletSelector |
| build_jetton_transfer |
--toAddress, --jettonAddress, --amount |
--comment, --walletSelector |
| build_nft_transfer |
--nftAddress, --toAddress |
--comment, --walletSelector |
| send_raw_transaction |
--messages |
--validUntil, --fromAddress, --walletSelector |
| emulate_transaction |
--messages |
--validUntil, --walletSelector |
build_ton_transfer、build_jetton_transfer、build_nft_transfer 只构建交易（返回 transaction.messages 以及 transaction.fromAddress），不会广播。需先用 emulate_transaction 预览，再用 send_raw_transaction --messages ... --fromAddress ... 广播。
兑换
| 工具 |
必需参数 |
可选参数 |
| get_swap_quote |
--fromToken, --toToken, --amount |
--slippageBps, --walletSelector |
NFT
| 工具 |
必需参数 |
可选参数 |
| get_nfts |
— |
--limit, --offset, --walletSelector |
| get_nfts_by_address |
--address |
--limit, --offset, --walletSelector |
| get_nft |
--nftAddress |
--walletSelector |
DNS
| 工具 |
必需参数 |
可选参数 |
| resolve_dns |
--domain |
--walletSelector |
| back_resolve_dns |
--address |
--walletSelector |
认证
| 工具 |
必需参数 |
可选参数 |
| generate_ton_proof |
--domain, --payload |
--walletSelector |
示例会话
# 检查钱包地址与网络
npx @ton/mcp@alpha get_wallet
# 检查 GRAM（例如 TON）余额
npx @ton/mcp@alpha get_balance
# 列出所有代币
npx @ton/mcp@alpha get_jettons
# 最近 10 笔交易
npx @ton/mcp@alpha get_transactions --limit 10
# 获取特定 jetton 的余额
npx @ton/mcp@alpha get_jetton_balance --jettonAddress EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs
# 解析 .ton 域名
npx @ton/mcp@alpha resolve_dns --domain foundation.ton
# 注册表模式下：查询命名钱包的余额
npx @ton/mcp@alpha get_balance --walletSelector "my-hot-wallet"
# 注册表模式下：列出所有已注册钱包
npx @ton/mcp@alpha list_wallets
# 发送 GRAM（例如 TON）——构建、预览，然后广播（广播前需与用户确认）
npx @ton/mcp@alpha build_ton_transfer --toAddress UQA... --amount 0.5 --comment "payment"
npx @ton/mcp@alpha emulate_transaction --messages '<transaction.messages>' # 推荐预览
npx @ton/mcp@alpha send_raw_transaction --messages '<transaction.messages>' --fromAddress '<transaction.fromAddress>'
# 兑换报价
npx @ton/mcp@alpha get_swap_quote --fromToken TON --toToken EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs --amount 1
# 为服务挑战生成 TonProof
npx @ton/mcp@alpha generate_ton_proof --domain getgems.io --payload getgems-llm
注意事项
- build_ton_transfer、build_jetton_transfer、build_nft_transfer 只构建交易；send_raw_transaction 才是签名并广播已准备好 transaction.messages 的工具（还需传入 transaction.fromAddress——jetton/NFT 消息绑定在其被构建时对应的钱包上）。
- 在广播前使用 emulate_transaction 预览预期余额变化（伪签名）。
- 仅在用户或验证服务提供了准确 domain 与 payload 时使用 generate_ton_proof；签名前不要改动 payload。
- generate_ton_proof 需要签名权限，尽管它不广播交易。
- build_ton_transfer、build_jetton_transfer、build_nft_transfer 与 emulate_transaction 不签名也不广播，可自由运行。仅在 send_raw_transaction（广播）之前，于使用 emulate_transaction 预览后与用户确认。
- 对于确认和小型选项集，优先使用宿主客户端提供的结构化确认或选择 UI（如果可用）；否则使用简短的自然语言是/否提示，绝不要要求精确的魔法词。
- 发送后，轮询 get_transaction_status --normalizedHash <hash>，直到状态为 completed 或 failed（除非用户要求跳过）。
- 注册表模式下，默认使用来自 ~/.config/ton/config.json 的活跃钱包。
