tonblockchainjettonsswapswallets
Reads TON liteserver data, contract state, jettons, swaps, cross-chain trades, and wallet details through MCP.
Quick Install
Automated & IDE SetupCopy the AI prompt to install this server into Claude Code, Cursor, or another agent ā or use 1-click editor setup below.
Not yet automatically verified
This server is confirmed live ā we successfully called its tools/list endpoint directly (see the verified badge above). We haven't yet sandbox-tested the stdio install command below specifically, which is a separate, ongoing check.
Manual Client & Custom JSON ConfigExpand JSON ā¾
Client Config & Setup
Choose your client or environment
Target File:
š” Paste the JSON block into your client's configuration file under mcpServers, then restart the application.
Overview
Use cases
Check whether a TON payment reached a wallet
Inspect a contract's deployment state and get-methods
Convert and compare TON address formats
Prepare a TON or cross-chain swap for wallet signing
Monitor an HTLC trade and build a refund when eligible
Key features
Native ADNL liteserver access
GRAM and jetton balance inspection
TON account and transaction queries
Read-only smart-contract get-methods
Unsigned TON and cross-chain swap transactions
TON wallet generation
Capabilities & Tool Schemas (16)
Inspect callable tools, capabilities, and parameters exposed to AI agents by Tonnode MCP.
get_masterchain_infoLatest TON masterchain block: workchain, shard, seqno and block hashes. Use when: checking that the network (or your endpoint) is alive and synced, or when you need the current block height. Returns: workchain, shard, seqno, rootHash/fileHash in base64. Tip: masterchain produces a block roughly every 3 seconds ā if seqno does not grow between calls, the liteserver is lagging.
get_balanceNative GRAM coin balance of a TON address (GRAM is the renamed Toncoin; the network is still called TON). Use when: the question is about the native coin only. For token balances (USDT and other jettons) use get_jetton_balance; for deployment status, code flags and the last transaction use get_account_state. Returns: balance_gram (decimal string, e.g. "12.5"), balance_nano (string, 1 GRAM = 1e9 nano) and at_seqno ā the masterchain block the reading is anchored to. Never-funded (uninitialized) addresses return 0 ā that is not an error.
get_account_stateFull account state of a TON address: status (active / frozen / uninit), GRAM balance, last-transaction pointer (lt + hash) and whether contract code/data are deployed. Use when: checking if a contract or wallet is deployed, diagnosing why an address does not respond, or before run_get_method (which needs status=active). Returns: status, balance_gram, last_transaction {lt (string), hash ā 64-char hex}, has_code, has_data, at_seqno. Reading the result: status=uninit with a non-zero balance means funds arrived but the wallet contract is not deployed yet; the last_transaction pointer is the cursor get_transactions starts from.
get_transactionsRecent transactions of a TON address, newest first. Use when: verifying that a payment arrived, listing latest wallet activity, or tracing what an address did recently. Returns an array of {hash, lt (string), unix_time, in_value_gram, in_from, out_messages, total_fees_gram} ā in_value_gram/in_from describe the incoming message (null for outgoing-only transactions). Never-active addresses return an empty array (not an error); an undecodable transaction comes back as {hash, parse_error: true}. No pagination: each call reads from the account's newest transaction ā at most the 30 most recent are reachable. History depth: an error like "lt not in db" means this liteserver has already pruned that part of history ā only archive endpoints keep the full chain; retry through one (TON_LITESERVERS or a TONNode hosted key) for deep history.
run_get_methodExecute a read-only get-method (no gas, no state change) on a smart contract: seqno, get_jetton_data, get_sale_data, get_collection_data and anything else the contract exposes. Use when: reading typed on-chain data from a specific contract. The contract must be active ā check with get_account_state first if unsure. Args: only integer arguments are supported here (decimal strings); methods that need an address/slice argument have dedicated tools ā e.g. use get_jetton_balance instead of calling get_wallet_address manually. Returns: exit_code (0 or 1 = success; 11 usually means the contract has no such method; other values are contract-specific errors) and the result stack ā typed items like {type:"int", value} or {type:"cell"|"slice", boc_base64}.
get_jetton_balanceJetton (TON token) balance of an owner address ā USDT and every other TEP-74 token. Use when: the question is about token balances rather than the native GRAM coin (for GRAM use get_balance). Args: owner ā the holder's address; jetton_master ā the token's master contract address. How it works: derives the owner's jetton-wallet address from the master, then reads its balance on-chain. Returns: jetton_wallet (the derived address), balance in raw indivisible units (string), deployed ā false means the owner never held this token, so the balance is 0 ā and at_seqno. Raw units: divide by 10^decimals; USDT uses 6 decimals, most other jettons 9 (read decimals from the master's metadata via run_get_method get_jetton_data).
How Tonnode MCP works
What tonnode/mcp MCP server does
The tonnode/mcp MCP server exposes direct access to The Open Network (TON) through MCP and the network's native ADNL liteserver protocol. It can connect through TON's free public configuration or through liteservers supplied by the operator. The package is intended for MCP clients and can also run in a Streamable HTTP mode for remote deployments.
Read operations cover the latest masterchain block, native GRAM balances, jetton balances and metadata, account status, recent transactions, and contract get-methods. Address input can be validated and converted locally between raw, bounceable, and non-bounceable forms. The server also includes TON swap and cross-chain workflows, plus a wallet-generation tool that returns secret key material.
This belongs in the Finance & Fintech category when an agent needs to inspect TON payments, read token data, prepare swaps, or monitor escrow-based cross-chain trades.
How it works
A local MCP setup starts the package with npx -y @tonnode/mcp. By default, it uses the public TON global configuration. TON_LITESERVERS can point it at private or hosted liteservers, while TON_CONFIG_URL selects an alternative configuration. TON_NETWORK=testnet or the corresponding command-line option selects the test network.
The read tools return data anchored to a masterchain sequence number where applicable. get_account_state can establish whether an address is active before run_get_method is used. Transaction reads are limited to the newest 30 reachable transactions and may fail for pruned history unless an archive-capable endpoint is used.
Swap execution remains non-custodial. get_swap_quote and get_crosschain_quote return firm, short-lived quotes; the matching build tools create unsigned TonConnect messages. Signing and broadcasting remain with the wallet owner. Cross-chain trades require tracking the escrow, disclosing the generated secret at the appropriate phase, or building a refund when the position becomes cancellable.
Setup and configuration
For a desktop MCP client, configure the command as npx with arguments -y and @tonnode/mcp. The README specifically provides examples for Claude Desktop, Claude Code, ChatGPT, Cursor, Codex, and other MCP clients.
HTTP mode starts with npx -y @tonnode/mcp --http. It listens on 127.0.0.1 by default and requires keys unless TONNODE_ALLOW_OPEN=1 is explicitly set. TONNODE_KEYS supplies comma-separated keys, while TONNODE_KEYS_FILE supports a hot-reloaded JSON key file. HTTP deployments can also set HOST, PORT, request and global rate limits, session limits, and session expiry. A TLS reverse proxy is recommended when exposing the service remotely.
OMNISTON_API_URL changes the Omniston WebSocket endpoint used by swap tools. TONNODE_DISABLE_WALLET_GEN=1 removes wallet generation, which is useful when the endpoint should not generate private key material.
Tools and capabilities
- Inspect masterchain sequence numbers, shards, and block hashes with
get_masterchain_info. - Read GRAM balances, jetton balances, token decimals, supply, minting status, and administrators.
- Check account deployment, status, balance, last transaction, code, and data flags.
- Read recent transactions and execute integer-argument contract get-methods without changing state.
- Normalize TON addresses offline with
parse_address. - Request TON mainnet DEX quotes and build unsigned swaps through Omniston, which aggregates STON.fi and DeDust liquidity.
- Quote and prepare TON-to-Ethereum, Arbitrum, Base, BNB, Polygon, or Avalanche trades using HTLC escrow tools.
- Generate wallets for v4, v3r2, v5r1, or highload_v3 contract versions.
The tonnode/mcp MCP server reports swap amounts in raw units. GRAM uses nine decimals, USDT uses six, and other jettons require their metadata to determine conversion. Generated mnemonics and private keys are returned to the caller; the server states that it does not store or log them, but losing the mnemonic means losing access to the wallet.
Limitations and notes
Swap quotes expire in about a minute and should be passed promptly to their build tools. Built transactions move real funds after signing, so applications should show the messages to the wallet owner. Cross-chain secrets must be kept private and retained until settlement or refund.
run_get_method supports integer arguments only; methods requiring address or slice arguments may need a dedicated tool. get_transactions has no pagination and cannot expose pruned history from a non-archive liteserver. Never-active addresses return empty transaction lists, and uninitialized addresses can return zero balance without indicating an error.
The generate-wallet tool creates a new independent wallet on every call. An undeployed wallet should receive its first deposit at the recommended non-bounceable address. The tonnode/mcp MCP server does not sign or broadcast transactions on behalf of the wallet owner.
Related MCP Servers
Adoption & maintenance
Factual signals from GitHub, npm, and our automated checks ā not a rating.
GitHub stars
27
Stargazers on the source repository.
Last commit
1mo ago
Most recent push to the default branch.
Tools exposed
16
Callable tools this server registers over MCP.
Directory activity
3 views
Config copies, upvotes, and views on AllMCPs.
Reviews
No reviews yet ā be the first to share how this listing worked for you.
Frequently Asked Questions about Tonnode MCP
AllMCPs Directory Badge
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
Badge Style:
Live Dynamic SVG Preview
Markdown (GitHub README)
[](https://allmcps.com/mcp/tonnode-mcp)HTML Embed
<a href="https://allmcps.com/mcp/tonnode-mcp"><img src="https://allmcps.com/api/badge/tonnode-mcp?style=directory" alt="Tonnode MCP on AllMCPs" /></a>