ton-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TON MCP Raw CLI Mode

TON MCP原生CLI模式

Run any TON wallet MCP tool directly from the command line. The binary invokes the tool, prints the JSON result to stdout, and exits.

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

Invocation Modes

调用模式

Command	Description
`npx @ton/mcp@alpha`	stdio MCP server (for Claude Desktop / MCP clients)
`npx @ton/mcp@alpha --http [port]`	HTTP MCP server
`npx @ton/mcp@alpha <tool_name> [--arg value ...]`	Raw CLI: call one tool and exit

Use exactly one mode for a given workflow: either MCP server mode (

stdio

--http

) or raw CLI. Do not combine them in the same task/session.

命令	描述
`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模式。请勿在同一任务/会话中混合使用。

Raw CLI Usage

原生CLI用法

bash

undefined

bash

undefined

No arguments

无参数

npx @ton/mcp@alpha get_balance

Named arguments (--key value)

命名参数（--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

所有值均以纯字符串传递；也接受JSON对象/数组

npx @ton/mcp@alpha get_transactions --limit 10 npx @ton/mcp@alpha send_ton --toAddress UQA... --amount 0.1 --comment "hi"


Arguments are passed as `--key value` pairs. Objects/arrays (`{...}` / `[...]`) are JSON-parsed; everything else is kept as a plain string.

npx @ton/mcp@alpha get_transactions --limit 10 npx @ton/mcp@alpha send_ton --toAddress UQA... --amount 0.1 --comment "hi"


参数以`--key value`对的形式传递。对象/数组（`{...}`/`[...]`）会被JSON解析；其他所有内容均保留为纯字符串。

Output

输出

All tools print JSON to stdout. Errors are printed to stderr and the process exits with code

bash

undefined

所有工具都会将JSON打印到stdout。错误信息会打印到stderr，进程将以代码

退出。

bash

undefined

Capture output for scripting

捕获输出用于脚本编写

BALANCE=$(npx @ton/mcp@alpha get_balance) echo $BALANCE | jq '.balance'

undefined

BALANCE=$(npx @ton/mcp@alpha get_balance) echo $BALANCE | jq '.balance'

undefined

Environment Variables

环境变量

The CLI respects the same environment variables as the server:

Variable	Description
`NETWORK`	`mainnet` (default) or `testnet`
`MNEMONIC`	24-word mnemonic for single-wallet mode
`PRIVATE_KEY`	Hex-encoded private key (alternative to mnemonic)
`WALLET_VERSION`	`v5r1` (default), `v4r2` , or `agentic`
`TONCENTER_API_KEY`	Optional Toncenter API key
`TON_CONFIG_PATH`	Path to config file (default: `~/.config/ton/config.json` )

Without

MNEMONIC

PRIVATE_KEY

, the CLI uses the local config registry at

~/.config/ton/config.json

(registry mode). In registry mode, wallet-scoped tools accept an optional

--walletSelector

to target a specific wallet by id, name, or address.

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、名称或地址定位特定钱包。

Tool Reference

工具参考

Wallet & Balance

钱包与余额

Tool	Required args	Optional args
`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`	—	—

工具	必填参数	可选参数
`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`	—	—

Wallet Registry (config-registry mode only)

钱包注册表（仅配置注册表模式）

Tool	Required args	Optional args
`list_wallets`	—	—
`get_current_wallet`	—	—
`set_active_wallet`	`--walletSelector`	—
`remove_wallet`	`--walletSelector`	—

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

Transfers

转账

Tool	Required args	Optional args
`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`

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

Swaps

兑换

Tool	Required args	Optional args
`get_swap_quote`	`--fromToken` , `--toToken` , `--amount`	`--slippageBps` , `--walletSelector`

工具	必填参数	可选参数
`get_swap_quote`	`--fromToken` , `--toToken` , `--amount`	`--slippageBps` , `--walletSelector`

NFTs

NFT

Tool	Required args	Optional args
`get_nfts`	—	`--limit` , `--offset` , `--walletSelector`
`get_nfts_by_address`	`--address`	`--limit` , `--offset` , `--walletSelector`
`get_nft`	`--nftAddress`	`--walletSelector`

工具	必填参数	可选参数
`get_nfts`	—	`--limit` , `--offset` , `--walletSelector`
`get_nfts_by_address`	`--address`	`--limit` , `--offset` , `--walletSelector`
`get_nft`	`--nftAddress`	`--walletSelector`

DNS

Tool	Required args	Optional args
`resolve_dns`	`--domain`	`--walletSelector`
`back_resolve_dns`	`--address`	`--walletSelector`

工具	必填参数	可选参数
`resolve_dns`	`--domain`	`--walletSelector`
`back_resolve_dns`	`--address`	`--walletSelector`

Example Session

示例会话

bash

undefined

bash

undefined

Check wallet address and network

检查钱包地址和网络

npx @ton/mcp@alpha get_wallet

Check TON balance

检查TON余额

npx @ton/mcp@alpha get_balance

List all tokens

列出所有代币

npx @ton/mcp@alpha get_jettons

Last 10 transactions

Get balance of a specific jetton

获取特定Jetton的余额

npx @ton/mcp@alpha get_jetton_balance --jettonAddress EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs

Resolve a .ton domain

解析.ton域名

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)

发送TON（请务必先获得用户确认）

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

undefined

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

undefined

Notes

注意事项

Use
```
emulate_transaction
```
to dry-run any transaction before sending — it returns expected balance changes, fees, and high-level actions
Always confirm with the user before running
```
send_ton
```
,
```
send_jetton
```
,
```
send_nft
```
, or
```
send_raw_transaction
```
;
For confirmations and small option sets, prefer the host client's structured confirmation/choice UI when available; otherwise use a short natural-language yes/no prompt and never require an exact magic word;
After sending, poll
```
get_transaction_status --normalizedHash <hash>
```
until status is
```
completed
```
or
```
failed
```
(unless the user asks to skip).
In registry mode the active wallet from
```
~/.config/ton/config.json
```
is used by default.

使用
```
emulate_transaction
```
在发送前预演任意交易——它会返回预期的余额变化、手续费和高级操作
在运行
```
send_ton
```
、
```
send_jetton
```
、
```
send_nft
```
或
```
send_raw_transaction
```
前，请务必获得用户确认；
对于确认操作和小型选项集，若可用则优先使用宿主客户端的结构化确认/选择UI；否则使用简短的自然语言是非提示，切勿要求输入特定的魔法词；
发送后，轮询
```
get_transaction_status --normalizedHash <hash>
```
直到状态变为
```
completed
```
或
```
failed
```
（除非用户要求跳过）。
在注册表模式下，默认使用
```
~/.config/ton/config.json
```
中的活跃钱包。

ton-cli

Original

Translation

TON MCP Raw CLI Mode

TON MCP原生CLI模式

Invocation Modes

调用模式

Raw CLI Usage

原生CLI用法

No arguments

无参数

Named arguments (--key value)

命名参数（--key value）

All values are passed as plain strings; JSON objects/arrays are also accepted

所有值均以纯字符串传递；也接受JSON对象/数组

Output

输出

Capture output for scripting

捕获输出用于脚本编写

Environment Variables

环境变量

Tool Reference

工具参考

Wallet & Balance

钱包与余额

Wallet Registry (config-registry mode only)

钱包注册表（仅配置注册表模式）

Transfers

转账

Swaps

兑换

NFTs

NFT

DNS

DNS

Example Session

示例会话

Check wallet address and network

检查钱包地址和网络

Check TON balance

检查TON余额

List all tokens

列出所有代币

Last 10 transactions

最近10笔交易

Get balance of a specific jetton

获取特定Jetton的余额

Resolve a .ton domain

解析.ton域名

In registry mode: check balances for a named wallet

注册表模式：检查指定名称钱包的余额

In registry mode: list all registered wallets

注册表模式：列出所有已注册的钱包

Send TON (always confirm with user first)

发送TON（请务必先获得用户确认）

Swap quote

获取兑换报价

Notes

注意事项