ton-cli

TON MCP Raw CLI Mode

コマンドラインから任意の 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 ...]	Raw CLI：ツールを 1 つ呼び出して終了

1 つのワークフローでは、いずれか 1 つのモードのみを使用してください。MCP サーバーモード（stdio／--http）または Raw CLI のどちらかを選びます。同じタスク／セッション内で併用しないでください。

Raw 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	16 進数でエンコードされた秘密鍵（ニーモニックの代わりに使用）
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 を実行する前に、必ずユーザーに確認してください。
• 確認や選択肢が少ない場合は、利用できるならホストクライアントの構造化された確認・選択 UI を優先してください。それ以外の場合は、簡潔な自然言語の yes/no プロンプトを使い、特定の合言葉の入力を決して必須にしないでください。
• 送信後は、ステータスが completed または failed になるまで get_transaction_status --normalizedHash <hash> をポーリングしてください（ユーザーがスキップを求めた場合を除きます）。
• レジストリモードでは、~/.config/ton/config.json のアクティブなウォレットがデフォルトで使用されます。