Skip to content
Skills Library
Programming · Tool integration

ton-cli

/ton-cli

Call TON MCP tools directly from the command line. Use when you want to query wallet info, check balances, send transactions, or run any TON wallet tool without starting an MCP server session. Works via `npx @ton/mcp@alpha <tool_name> [--arg value ...]`.

Repository
kit ↗
Licence
MIT
Last repository change
08.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Call TON MCP tools directly from the command line. Use when you want to query wallet info, check balances, send transactions, or run any TON wallet tool without starting an MCP server session. Works via `npx @ton/mcp@alpha <tool_name> [--arg value ...]`.

Original author description

Call TON MCP tools directly from the command line. Use when you want to query wallet info, check balances, send transactions, or run any TON wallet tool without starting an MCP server session. Works via `npx @ton/mcp@alpha <tool_name> [--arg value ...]`.

How it works

  1. Invocation Modes
  2. Raw CLI Usage
  3. Output
  4. Environment Variables
  5. Tool Reference
  6. Example Session
  7. Notes
Original SKILL.md headings · 173 lines, 1,023 words
SKILL.md preview
---
name: ton-cli
description: Call TON MCP tools directly from the command line. Use when you want to query wallet info, check balances, send transactions, or run any TON wallet tool without starting an MCP server session. Works via `npx @ton/mcp@alpha <tool_name> [--arg value ...]`.
user-invocable: true
disable-model-invocation: false
allowed-tools: ["Bash(npx @ton/mcp@alpha *)"]
---

# 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

```bash
# 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`.

```bash
# 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

```bash
# 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.

Versions

The database has no other skills named ton-cli.

Database snapshot: 13.11.2026 · package version b3297daf3072 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90ton-balance
    Check TON wallet balances, token holdings, and transaction history. Use when the user wants to check their balance, see how much GRAM (ex. TON) they have, list tokens, view jettons, check transaction history, look up a token, or verify a transaction status.
  • 100ton-appkit
    Use this skill whenever the user is building an app with @ton/appkit or @ton/appkit-react as a library consumer: setup, TonConnect wallet connection, balances, sending TON/jettons/NFTs, swaps, staking, signing, real-time WebSocket updates, cache invalidation, mainnet/testnet…
  • 100tonapi
    Work with TON blockchain via the tonapi Python SDK — query accounts, transactions, jettons, NFTs, staking, validator rewards, DNS, prepare wallet migration, emulate messages, subscribe to real-time events, and manage webhooks. Use this skill whenever the user mentions TONAPI,…
  • 100k8s-cli
    kubectl-mcp-server CLI commands for tool discovery, direct invocation, and diagnostics. Use when exploring available tools, calling tools from command line, or checking server health.
  • 100mcp-cli
    Interface for MCP (Model Context Protocol) servers via CLI. Use when you need to interact with external tools, APIs, or data sources through MCP servers, list available MCP servers/tools, or call MCP tools from command line.
  • 100ton-analyst
    Analyze TON blockchain data using Dune Analytics. Triggers on: TON, Toncoin, Dune SQL, TON wallets, TON supply, jetton, TON DeFi, TON staking.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.