@tonnode/mcp
MCP server that gives AI agents direct liteserver access to The Open Network (TON) — no HTTP gateways in the middle. Balances, account state, transaction history and contract get-methods over TON's native ADNL protocol.
Built by TONNode — private TON liteservers, archive nodes, mempool stream and indexed API.
Quick start
Add to Claude Desktop, Claude Code, ChatGPT, Cursor, Codex or any MCP client:
{
"mcpServers": {
"ton": {
"command": "npx",
"args": ["-y", "@tonnode/mcp"]
}
}
}
That's the whole integration. The server connects to TON mainnet via the public global config by default.
Naming note: the native coin was renamed from Toncoin to GRAM in June 2026; the network itself is still called TON. Tool outputs use *_gram fields.
| Tool | What it does |
|---|
get_masterchain_info | Current masterchain head: seqno, shard, block hashes |
get_balance | GRAM balance of an address (GRAM + nano) |
get_account_state | Status (active/frozen/uninit), balance, last-tx pointer, code/data flags |
get_transactions | Recent transactions: lt, time, incoming value, fees |
run_get_method | Read-only get-methods on contracts (seqno, get_wallet_address, …) |
Hosted / self-hosted HTTP mode
The package also ships a Streamable-HTTP entry for remote deployments (this is what powers mcp.tonnode.io):
TONNODE_KEYS=tn_live_abc,tn_live_def PORT=8808 npx -y @tonnode/mcp --http
Clients then connect without installing anything:
{
"mcpServers": {
"ton": {
"url": "https://your-host/mcp",
"headers": { "Authorization": "Bearer tn_live_abc" }
}
}
}
Requests are authenticated with Bearer keys from TONNODE_KEYS (comma-separated) and rate-limited per key (RATE_LIMIT_RPM, default 300). Sessions are private to the key that opened them, idle sessions are swept after SESSION_TTL_MIN (default 30 minutes), and concurrent sessions are capped per key and globally. Without TONNODE_KEYS the server refuses to start; set TONNODE_ALLOW_OPEN=1 to explicitly run keyless behind your own firewall. GET /healthz for monitoring.
The server binds 127.0.0.1 by default — put a TLS reverse proxy (Caddy, nginx) in front and set HOST=0.0.0.0 only if the proxy runs on another machine. Ready-made systemd + Caddy configs live in deploy/.
Configuration
| Env var | Meaning |
|---|
TON_LITESERVERS | Use your own liteservers instead of the public config: [{"ip":"1.2.3.4","port":40004,"key":"<base64 ed25519>"}] |
TON_CONFIG_URL | Alternative global-config URL |
TON_NETWORK=testnet | Use the testnet config (or pass --testnet) |
TONNODE_KEYS | HTTP mode: comma-separated Bearer API keys |
HOST | HTTP mode: bind address (default 127.0.0.1) |
PORT | HTTP mode: listen port (default 8808) |
RATE_LIMIT_RPM | HTTP mode: requests per minute per key (default 300) |
SESSION_TTL_MIN | HTTP mode: idle minutes before a session is swept (default 30) |
MAX_SESSIONS / MAX_SESSIONS_PER_KEY | HTTP mode: concurrent session caps (default 500 / 50) |
A note on public liteservers
The default public-config liteservers are shared, rate-limited and keep no deep history — get_transactions beyond recent blocks will answer lt not in db. Agents also tend to query in bursts, which public gateways throttle.
For guaranteed throughput, archive depth and a node-level mempool stream, point TON_LITESERVERS at a private endpoint — tonnode.io provisions one in under a minute, payable in TON.
License
MIT © TONNode