# TONNode — TON blockchain access (npm · @tonnode/mcp)

Liteserver access to TON: balances, account state, transactions and get-methods over native ADNL.

- Trust score: 68/100 (medium)
- Change this week: +25
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-06

## Components

- npm · `@tonnode/mcp`: 68/100 (this document), [markdown](https://verifymcp.io/servers/tonnode-mcp/tonnode-mcp.md), [page](https://verifymcp.io/servers/tonnode-mcp/tonnode-mcp)

## Channel facts

- Registry: `npm`
- Package: `@tonnode/mcp`
- Version: `0.5.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-06.

- **Supply Chain Security**: 88/100
  - No malware found by supply-chain analysis.
  - Known CVEs were checked across the 119 of 123 dependencies we could resolve, so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Dependency health was assessed across the 119 of 123 dependencies we could resolve, so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 10 days ago).
  - Security-disclosure policy not yet verified: we couldn't inspect the source repository.
- **Schema Quality & AI Usability**: 65/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 1416 tokens (~202/item across 7 items; 7 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 33/100
  - Stability observed for 10 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add tonnode-mcp -- npx -y @tonnode/mcp
```

### Codex

```bash
codex mcp add tonnode-mcp -- npx -y @tonnode/mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tonnode-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@tonnode/mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add tonnode-mcp --command npx --arg -y --arg @tonnode/mcp
```

### Hermes

```yaml
mcp_servers:
  tonnode-mcp:
    command: "npx"
    args: ["-y", "@tonnode/mcp"]
```

### Other

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

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-06 (score 68, 0)

- [functional regression] Security disclosure: fail → unverified

### 2026-08-05 (score 68, +1)

No change was recorded against any check on this day. Stability & Change Management went from 27 to 30. That category is still filling its 30-day observation window: 8 days of observed history at the previous scan, 9 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-08-04 (score 67, +4)

- [functional improvement] Stability: unverified → 0.27

### 2026-08-03 (score 63, +43)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional] Licence: MIT

### 2026-08-02 (score 20, +2)

- [security improvement] Malware scan: unverified → pass
- [functional regression] Tool coverage: 100 → unverified

### 2026-08-01 (score 18, +13)

- [functional improvement] Tool coverage: unverified → 100

### 2026-07-31 (score 5, −38)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-27 (score 43)

First indexed and scored.

## MCP tools (7)

### `get_masterchain_info` (~101 tokens)

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.

Output parameters:

- `fileHash` (string)
- `rootHash` (string)
- `seqno` (number)
- `shard` (string)
- `workchain` (number)

### `get_balance` (~173 tokens)

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

Input parameters:

- `address` (string, required): TON address in friendly (EQ…/UQ…) or raw (0:… / -1:…) form

Output parameters:

- `address` (string)
- `at_seqno` (number)
- `balance_gram` (string)
- `balance_nano` (string)

### `get_account_state` (~178 tokens)

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.

Input parameters:

- `address` (string, required): TON address in friendly (EQ…/UQ…) or raw (0:… / -1:…) form

Output parameters:

- `address` (string)
- `at_seqno` (number)
- `balance_gram` (string)
- `has_code` (boolean)
- `has_data` (boolean)
- `last_transaction`
- `status` (string)

### `get_transactions` (~244 tokens)

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

Input parameters:

- `address` (string, required): TON address in friendly (EQ…/UQ…) or raw (0:… / -1:…) form
- `limit` (integer): How many transactions to return, 1–30 (default 10)

Output parameters:

- `address` (string)
- `transactions` (array)

### `run_get_method` (~257 tokens)

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

Input parameters:

- `address` (string, required): TON address in friendly (EQ…/UQ…) or raw (0:… / -1:…) form
- `args` (array): Integer arguments as decimal strings, e.g. ["0"] (most methods take none)
- `method` (string, required): get-method name, e.g. "seqno" or "get_jetton_data"

Output parameters:

- `address` (string)
- `exit_code` (number)
- `method` (string)
- `stack` (array)

### `get_jetton_balance` (~269 tokens)

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

Input parameters:

- `jetton_master` (string, required): Jetton master contract address, e.g. USDT "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs"
- `owner` (string, required): Holder's TON address, friendly (EQ…/UQ…) or raw (0:… / -1:…) form

Output parameters:

- `at_seqno` (number)
- `balance` (string)
- `deployed` (boolean)
- `jetton_master` (string)
- `jetton_wallet` (string)
- `owner` (string)

### `parse_address` (~194 tokens)

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.

Input parameters:

- `address` (string, required): TON address in any form: friendly (EQ…/UQ…) or raw (0:… / -1:…)

Output parameters:

- `friendly_bounceable` (string)
- `friendly_non_bounceable` (string)
- `input_flags`
- `input_format` (string)
- `raw` (string)
- `workchain` (number)

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/tonnode-mcp/tonnode-mcp#diagnostics

## Score history

- 2026-08-06: 68
- 2026-08-05: 68
- 2026-08-04: 67
- 2026-08-03: 63
- 2026-08-02: 20
- 2026-08-01: 18
- 2026-07-31: 5
- 2026-07-30: 43
- 2026-07-28: 43
- 2026-07-27: 43

## Links

- npm package: https://www.npmjs.com/package/@tonnode/mcp
- Socket report: https://socket.dev/npm/package/@tonnode/mcp
- Repository: https://github.com/tonnode/mcp
- Website: https://tonnode.io/mcp
- Changelog RSS feed: https://verifymcp.io/servers/tonnode-mcp/tonnode-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/tonnode-mcp/tonnode-mcp.json
- HTML version of this page: https://verifymcp.io/servers/tonnode-mcp/tonnode-mcp