TONNode

Direct liteserver access to The Open Network (TON) for AI agents — no HTTP gateways in the middle.

CommunityOnlineNo sign-inGlobalFreeCan modify data

What it can do

  • 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 b
  • 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 an
  • 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: che

What data it sees

Do you need an account

No: the server works without sign-in

Direct liteserver access to The Open Network (TON) for AI agents — no HTTP gateways in the middle. Backed by TONNode private infrastructure over native ADNL.

Tools

  • get_balance — native GRAM balance of any address
  • get_jetton_balance — USDT and any other jetton balance, jetton wallet derived on-chain
  • get_transactions — recent transactions with values, senders and fees
  • get_account_state — status, deployment flags, last-tx pointer
  • run_get_method — read-only contract get-methods (seqno, get_jetton_data, …)
  • parse_address — convert/validate EQ…/UQ…/raw address forms, offline
  • get_masterchain_info — network liveness, latest block

Connection: get an API key at tonnode.io/mcp and paste it as apiKey.

Prefer running locally? npx -y @tonnode/mcp — free via the public TON config (GitHub).

How to connect

How to connect TONNode to Claude

The server address to paste into Claude settings:

https://tonnode--tonnode.run.tools

  1. Open Claude (claude.ai or the desktop app).
  2. Go to Settings → Connectors.
  3. Click Add custom connector.
  4. Paste the server address copied below into Remote MCP server URL and click Add.
  5. In a chat, click + → Connectors and switch the new connector on.

Custom connectors are available on Free, Pro, Max, Team and Enterprise plans (Free is limited to one). On Team and Enterprise an organization Owner adds the connector first under Organization settings → Connectors.

Authorization

After you click Add, a sign-in window for the service opens. Sign in with your own account and approve access. Claude never sees your password.

How to connect TONNode to ChatGPT

The server address to paste into ChatGPT settings:

https://tonnode--tonnode.run.tools

  1. Open ChatGPT in a browser (chatgpt.com). A Plus, Pro, Business, Enterprise or Edu plan is required.
  2. Turn on developer mode once: Settings → Apps → Advanced settings → Developer mode.
  3. Open Settings → Connectors and click Create.
  4. Fill in the form: Name (anything), Description (one line about what the service does), MCP server URL (copy it below).
  5. Under Authentication choose OAuth if the service requires sign-in, otherwise None. Click Create.
  6. In a new chat open + → Apps/Connectors and enable the connector.

OpenAI has renamed this section before (Connectors → Apps/Plugins). If the label differs, search settings for "developer mode". On Business/Enterprise workspaces an admin must allow custom connectors first.

Authorization

On first use ChatGPT opens the service's sign-in window. Sign in and approve access.

How to connect TONNode to Cursor

The server address to paste into Cursor settings:

https://tonnode--tonnode.run.tools

Fastest: click Open in Cursor below and confirm the prompt.

Manually:

  1. In Cursor open Settings → Cursor Settings → MCP and click Add new global MCP server.
  2. Paste the JSON copied below into ~/.cursor/mcp.json (per project: .cursor/mcp.json in the repo root).
  3. Save the file. The server appears in the MCP list; authorize it there if asked.

Authorization

If the service needs sign-in, an authorize button appears next to the server in the MCP list.

Server tool list (7)

Raw names from tools/list. Only developers need these.

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).
parse_addressParse, 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.