# tonnode/mcp [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/tonnode/mcp  
**GitHub Stars:** 27  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/tonnode-mcp

## Description
Direct liteserver access to The Open Network (TON) over native ADNL: GRAM balances, account state, transaction history and contract get-methods. Works with the free public config or a private/hosted endpoint. npx -y @tonnode/mcp

## Tools
Capabilities this server exposes over MCP:

- **get_masterchain_info** — Latest 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_balance** — Native 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_state** — Full 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_transactions** — Recent 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_method** — Execute 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_balance** — Jetton (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).
- **get_jetton_info** — Metadata of a jetton master (token) contract: name, symbol, DECIMALS, total supply, mintable, admin. Use when: you need a token's decimals to convert raw indivisible units — swap quotes and balances are in raw units, so a human amount = raw / 10^decimals (USDT is 6, most jettons 9). Call this before get_swap_quote/build_swap_tx when you don't know the token's decimals. Args: jetton_master — the token's master contract address (e.g. USDT "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs"). Returns: name, symbol, decimals (a number, or null when the token stores metadata off-chain), description, total_supply (raw), mintable, admin, metadata_type (onchain/offchain) and metadata_uri. Off-chain tokens keep name/symbol/decimals in a JSON file at metadata_uri — this tool returns the URI but does not fetch it, so decimals may be null (assume 6 for USDT-like, 9 otherwise, or fetch the URI).
- **parse_address** — Parse, validate and convert a TON address between all its formats — purely local, no network access. Use when: normalizing user input, comparing addresses that look different but may be the same account, or converting to the raw form that indexers and APIs expect. Accepts friendly (EQ…/UQ…, with or without URL-safe characters) and raw (workchain:hex) forms. Returns: raw, friendly_bounceable (EQ…), friendly_non_bounceable (UQ…), workchain and flags of the given input. Background: EQ… and UQ… encode the SAME account — EQ (bounceable) is conventional for contracts, UQ (non-bounceable) for user wallets; two addresses are equal if their raw forms match.
- **get_swap_quote** — Firm swap quote for exchanging GRAM or any jetton into another asset on TON, via the Omniston protocol (STON.fi RFQ aggregation over STON.fi/DeDust liquidity). MAINNET only. Use when: an agent wants to know the current exchange terms, or as step 1 of an actual swap (step 2 is build_swap_tx with the returned quote_id). For swaps INTO another blockchain (ETH, Base, BNB…) use get_crosschain_quote instead. Amounts are raw indivisible units — GRAM has 9 decimals (1 GRAM = 1e9), USDT has 6; read a jetton's decimals via run_get_method get_jetton_data if unsure. Returns: quote_id (pass it to build_swap_tx PROMPTLY — quotes expire in about a minute), input/output amounts, min_output_units (the on-chain slippage floor the swap will be built with — the only guaranteed minimum), price_impact_bps, integrator_fee_units (revenue share of the server operator, if configured — already deducted from output_units), gas_budget_nano (GRAM the wallet must additionally hold for gas) and the DEX route. This is a price lookup only — nothing is signed or sent.
- **build_swap_tx** — Build the UNSIGNED transaction for a swap quoted by get_swap_quote. Non-custodial: this returns TonConnect-ready messages — nothing is signed and nothing is sent; the wallet owner signs and broadcasts them (e.g. tonConnectUi.sendTransaction(result.tonconnect)). The messages MOVE REAL FUNDS once signed, so treat the output as an armed payment and show it to the wallet owner before sending. Use when: an agent (or the app driving it) actually wants to execute the swap after inspecting the quote. Args: quote_id from get_swap_quote (use it promptly — expired quotes fail and need a re-quote) and wallet — the address that will send the transaction, receive the swap output and any gas excess. Returns: tonconnect {validUntil, network, messages[{address, amount, payload, stateInit?}]} with base64 BoC payloads, exactly the shape TonConnect sendTransaction expects. Omniston emulates the transfer while building — if the wallet lacks the input funds, this fails up front. The wallet must hold the input amount (for GRAM swaps it is included in the attached value) plus the quote's gas_budget_nano in GRAM.
- **get_crosschain_quote** — Firm quote for swapping GRAM or a TON jetton into an asset on another blockchain (Ethereum, Arbitrum, Base, BNB, Polygon, Avalanche) via Omniston's atomic HTLC escrow settlement. MAINNET only. TON is always the source chain — the trade is initiated and funded by a TON wallet. Use when: an agent needs USDT/USDC/native coins delivered to an EVM address, paid from TON. Step 2 is build_crosschain_swap_tx with the returned quote_id. Amounts are raw indivisible units of each asset (TON USDT = 6 decimals, GRAM = 9, EVM tokens per their own decimals). Returns: quote_id (use PROMPTLY — quotes expire in about a minute), input/output amounts, fees, gas_budget_nano (GRAM needed for gas on TON), security_deposit (extra value temporarily locked in the escrow, returned on completion), htlc_hashing_function (COPY IT VERBATIM into build_crosschain_swap_tx) and estimated_settlement_seconds for the full cross-chain trade. This is a price lookup only — nothing is signed or sent.
- **build_crosschain_swap_tx** — Build the UNSIGNED TON escrow transaction for a cross-chain swap quoted by get_crosschain_quote, and generate the HTLC secret that later completes it. Non-custodial: nothing is signed or sent, and the server does NOT keep the secret — it exists only in this response. The messages MOVE REAL FUNDS once signed; treat the output as an armed payment. Treat htlc_secret like a payment authorization: anyone who sees it together with quote_id can trigger disclosure — keep this response out of logs and shared contexts. EVERY CALL GENERATES A NEW SECRET bound to THIS tonconnect payload — if you rebuild for the same quote, discard every earlier payload and secret; signing an older payload after a rebuild locks funds under a hash whose secret you no longer track. THE FLOW AFTER THIS CALL: (1) the wallet owner signs and sends result.tonconnect; (2) poll track_crosschain_swap every ~10s; (3) when an execution's dst_phase reaches ready_for_private_completion, call disclose_crosschain_secret PROMPTLY with htlc_secret (the tool re-verifies the on-chain state before revealing anything); (4) if nothing fills and cancellation_mode becomes onchain, reclaim funds with build_crosschain_refund. STORE htlc_secret UNTIL THE TRADE COMPLETES — without it the trade cannot settle (funds remain refundable after the timeout, but the swap is lost).
- **track_crosschain_swap** — Current status of a cross-chain swap: the escrow order created from a get_crosschain_quote quote, with per-execution lifecycle phases and HTLC time windows on both chains. Use when: after sending the escrow transaction built by build_crosschain_swap_tx — poll every ~10s. Reading the result: found=false means the escrow transaction has not landed yet (or was never sent); when an execution's dst_phase reaches ready_for_private_completion, call disclose_crosschain_secret promptly — do NOT disclose if now is close to that execution's output_position_timestamps.private_rollback_at (unix seconds): past it the resolver can roll the destination back, and a late reveal risks losing the input without receiving the output. status becomes fully_filled once settled; cancellation_mode=onchain means funds can be reclaimed with build_crosschain_refund. Returns a snapshot, not a stream — poll again for updates.
- **disclose_crosschain_secret** — Reveal the HTLC secret from build_crosschain_swap_tx to settle a cross-chain swap. This is the final, trade-committing step: once revealed the preimage is public and the resolver can claim the TON side — it CANNOT be taken back. Before revealing anything, the tool re-verifies live state and refuses unless ALL of these hold: the order exists on-chain, the destination position is at ready_for_private_completion or ready_for_public_completion, and the secret matches that execution's on-chain hash. Call it as soon as track_crosschain_swap shows dst_phase=ready_for_private_completion — a prompt reveal keeps a wide safety margin before the destination's rollback window opens. The secret can only complete the trade as quoted; it cannot redirect funds.
- **build_crosschain_refund** — Build the UNSIGNED transaction that cancels a cross-chain escrow position and returns the funds to the owner wallet. Use when: a cross-chain swap did not settle — track_crosschain_swap shows cancellation_mode=onchain (before that the position cannot be cancelled by the trader). Non-custodial: returns TonConnect-ready messages for the SAME wallet that created the escrow; nothing is signed or sent here. After signing and sending, the escrowed input (and the security deposit) come back to the owner.
- **generate_wallet** — Create a brand-new TON wallet: a fresh 24-word mnemonic, its ed25519 keypair, and the wallet address for the chosen contract version. Use when an agent needs its own wallet to receive or send funds (e.g. before build_swap_tx). SECURITY — READ BEFORE USE: this returns SECRET key material (mnemonic + private key). Anyone who sees this response controls the wallet and any funds in it. In hosted mode the keys are generated on the server and returned over TLS, so treat the wallet as HOT: fine for programmatic/ephemeral use, but move any significant balance to a hardware or cold wallet, and keep this response out of logs and shared transcripts. The server does not store or log the mnemonic or private key — only the public address. Losing the mnemonic means losing the funds; there is no recovery. Versions: v4 (most common, recommended default), v3r2 (simple/legacy), v5r1 (W5 — gasless-capable, newest), highload_v3 (mass-payout wallet for exchanges/payment systems). For highload_v3 the address also depends on subwallet_id and timeout_sec (they are part of the contract data), so changing them changes the address; the defaults match standard tooling — store them ALONGSIDE the mnemonic, as the mnemonic alone cannot reproduce a highload address with non-default params. EACH CALL CREATES A NEW, INDEPENDENT WALLET — never re-call this tool to 're-read' a wallet you already made; you will get a different one and orphan any funds sent to the first. Returns: address (recommended_deposit_address plus bounceable EQ…, non_bounceable UQ… and raw forms), public_key and private_key (hex), the 24-word mnemonic, plus version and workchain. The address is UNINITIALIZED until the wallet is deployed by its first outgoing transaction — receiving funds does not require deployment, but the FIRST deposit must be sent to the non_bounceable (UQ…) address: a bounceable send to an undeployed wallet bounces back to the sender. Use recommended_deposit_address for incoming funds.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp": {
    "command": "npx",
    "args": ["-y","@tonnode/mcp"]
  }
}
```

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/tonnode-mcp/readme_