ton-cli

TON MCP Raw CLI Mode

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

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.

Raw CLI Usage

# 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 build_ton_transfer --toAddress UQA... --amount 0.1 --comment "hi"
npx @ton/mcp@alpha generate_ton_proof --domain getgems.io --payload getgems-llm

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

Output

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

# Capture output for scripting
BALANCE=$(npx @ton/mcp@alpha get_balance)
echo $BALANCE | jq '.balance'

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 or 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.

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	—	—

Wallet Registry (config-registry mode only)

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

Transfers

Tool	Required args	Optional args
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 only build a transaction (return transaction.messages plus transaction.fromAddress); they do not broadcast. Preview with emulate_transaction, then broadcast with send_raw_transaction --messages ... --fromAddress ....

Swaps

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

NFTs

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

Authentication

Tool	Required args	Optional args
generate_ton_proof	--domain, --payload	--walletSelector

Example Session

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

# Check GRAM (ex. 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 GRAM (ex. TON) — build, preview, then broadcast (confirm with user before the broadcast step)
npx @ton/mcp@alpha build_ton_transfer --toAddress UQA... --amount 0.5 --comment "payment"
npx @ton/mcp@alpha emulate_transaction --messages '<transaction.messages>'        # recommended preview
npx @ton/mcp@alpha send_raw_transaction --messages '<transaction.messages>' --fromAddress '<transaction.fromAddress>'

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

# Generate a TonProof for a service challenge
npx @ton/mcp@alpha generate_ton_proof --domain getgems.io --payload getgems-llm

Notes

• build_ton_transfer/build_jetton_transfer/build_nft_transfer build a transaction only; send_raw_transaction is the tool that signs and broadcasts the prepared transaction.messages (pass transaction.fromAddress too — jetton/NFT messages are bound to the wallet they were built for)
• Use emulate_transaction to preview expected balance changes before broadcasting (fake signature)
• Use generate_ton_proof only with the exact domain and payload supplied by the user or verifying service; do not alter the payload before signing
• generate_ton_proof requires signing access even though it does not broadcast a transaction
• build_ton_transfer/build_jetton_transfer/build_nft_transfer and emulate_transaction do not sign or broadcast — run them freely. Confirm with the user only before send_raw_transaction (the broadcast), after previewing with emulate_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.