ton-cli

TON MCP 原始 CLI 模式

直接从命令行运行任意 TON 钱包 MCP 工具。二进制文件会调用该工具，将 JSON 结果打印到标准输出，然后退出。

调用模式

命令	说明
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 用法

# No arguments
npx @ton/mcp@alpha get_balance

# Named arguments (--key value)
npx @ton/mcp@alpha get_transactions --limit 5
npx @ton/mcp@alpha get_jetton_balance --jettonAddress EQAbc...

# All values are passed as plain strings; JSON objects/arrays are also accepted
npx @ton/mcp@alpha get_transactions --limit 10
npx @ton/mcp@alpha send_ton --toAddress UQA... --amount 0.1 --comment "hi"

参数以 --key value 键值对形式传递。对象/数组（{...} / [...]）会按 JSON 解析；其他内容均作为普通字符串保留。

输出

所有工具都会将 JSON 打印到标准输出。错误会打印到标准错误，进程以代码 1 退出。

# Capture output for scripting
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 密钥
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	—	—

钱包注册表（仅限 config-registry 模式）

工具	必需参数	可选参数
list_wallets	—	—
get_current_wallet	—	—
set_active_wallet	--walletSelector	—
remove_wallet	--walletSelector	—

转账

工具	必需参数	可选参数
send_ton	--toAddress、--amount	--comment、--walletSelector
send_jetton	--toAddress、--jettonAddress、--amount	--comment、--walletSelector
send_nft	--nftAddress、--toAddress	--comment、--walletSelector
send_raw_transaction	--messages	--validUntil、--fromAddress、--walletSelector
emulate_transaction	--messages	--validUntil、--walletSelector

兑换

工具	必需参数	可选参数
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

示例会话

# Check wallet address and network
npx @ton/mcp@alpha get_wallet

# Check TON balance
npx @ton/mcp@alpha get_balance

# List all tokens
npx @ton/mcp@alpha get_jettons

# Last 10 transactions
npx @ton/mcp@alpha get_transactions --limit 10

# Get balance of a specific jetton
npx @ton/mcp@alpha get_jetton_balance --jettonAddress EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs

# Resolve a .ton domain
npx @ton/mcp@alpha resolve_dns --domain foundation.ton

# In registry mode: check balances for a named wallet
npx @ton/mcp@alpha get_balance --walletSelector "my-hot-wallet"

# In registry mode: list all registered wallets
npx @ton/mcp@alpha list_wallets

# Send TON (always confirm with user first)
npx @ton/mcp@alpha send_ton --toAddress UQA... --amount 0.5 --comment "payment"

# Swap quote
npx @ton/mcp@alpha get_swap_quote --fromToken TON --toToken EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs --amount 1

注意事项

• 发送任何交易前，使用 emulate_transaction 进行试运行；它会返回预期余额变化、费用和高级操作
• 运行 send_ton、send_jetton、send_nft 或 send_raw_transaction 前，务必先征得用户确认；
• 对于确认和选项较少的情况，优先使用宿主客户端提供的结构化确认／选择界面；否则，使用简短的自然语言是／否提示，绝不要求用户输入特定的口令；
• 发送后，轮询 get_transaction_status --normalizedHash <hash>，直到状态为 completed 或 failed（除非用户要求跳过）。
• 在注册表模式下，默认使用 ~/.config/ton/config.json 中的活动钱包。