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

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

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

—

get_jetton_balance

--jettonAddress

--walletSelector

get_jettons

— --walletSelector

get_jettons_by_address

--address

—

get_jetton_info

--jettonAddress

—

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

send_ton

--toAddress , --amount

--comment , --walletSelector

send_jetton

--toAddress , --jettonAddress , --amount

--comment , --walletSelector

send_nft

--nftAddress , --toAddress

--comment , --walletSelector

send_raw_transaction

--messages

--walletSelector

Swaps

Tool Required args Optional args

get_swap_quote

--fromToken , --toToken , --amount

--walletSelector

NFTs

Tool Required args Optional args

get_nfts

— --limit , --offset , --walletSelector

get_nfts_by_address

--address

--limit , --offset

get_nft

--nftAddress

—

DNS

Tool Required args

resolve_dns

--domain

back_resolve_dns

--address

Example Session

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

Notes

• Always confirm with the user before running send_ton , send_jetton , send_nft , or send_raw_transaction .

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