AI 클라이언트가 TON liteserver에 직접 쿼리하여 잔액, 계정 상태, 트랜잭션, get-method를 조회하고 서명되지 않은 스왑을 생성할 수 있습니다.
다른 이름 tonnode/mcp, mcp, @tonnode/mcp
- 스타
- 20
- Tools
- 16
- 다운로드, 30일
- —
- 최신 버전
- 0.9.2
- 마지막 커밋
- 2026년 10월 8일
- 라이선스
- MIT
TON MCP란?
TON은(는) MCP server입니다. AI 클라이언트가 TON liteserver에 직접 쿼리하여 잔액, 계정 상태, 트랜잭션, get-method를 조회하고 서명되지 않은 스왑을 생성할 수 있습니다. 16개 도구를 제공합니다. 예: get_balance, get_jetton_balance, get_jetton_info.
프로젝트 README에서 생성된 요약
TON MCP server 정보
이 서버는 AI 에이전트가 TON 블록체인을 직접 조회할 수 있도록 지원합니다. 네이티브 ADNL 프로토콜을 통해 liteserver에 직접 접근함으로써 기존의 HTTP 게이트웨이를 거치지 않고 계정 상태, 트랜잭션 내역, jetton 잔액을 가져옵니다. 개발자는 로컬 사용을 위해 간단한 npx 명령어를 사용하거나, 원격 배포를 위해 hosted HTTP 엔드포인트를 사용하여 Claude Desktop, Cursor 또는 ChatGPT와 같은 클라이언트에 통합할 수 있습니다.
단순한 데이터 조회를 넘어, 이 서버는 에이전트가 트레이더 역할을 수행할 수 있게 합니다. Omniston 프로토콜을 사용하여 GRAM 및 다양한 jetton에 대한 서명되지 않은 스왑 트랜잭션 생성을 지원하며, Ethereum, Arbitrum, Avalanche와 같은 네트워크를 포함하는 복잡한 크로스체인 스왑 관리도 가능합니다. 또한 v4 또는 highload_v3와 같은 특정 컨트랙트 버전의 새 지갑을 생성하는 도구도 포함되어 있습니다. hosted 버전을 사용하는 경우, 서버는 Bearer key를 통해 인증을 관리하고 안정적인 성능을 보장하기 위해 세밀한 rate limiting을 제공합니다.
활용 사례
- 1지갑 잔액 확인AI 에이전트가 특정 주소의 현재 GRAM 또는 USDT 보유량을 확인할 수 있습니다.
- 2탈중앙화 스왑 준비개발자가 AI에게 지갑에서 서명할 준비가 된 토큰 교환용 서명되지 않은 트랜잭션 생성을 요청할 수 있습니다.
- 3크로스체인 거래 실행에이전트가 TON에서 Polygon 또는 Base와 같은 네트워크로 자산을 이동하는 거래의 라이프사이클을 관리할 수 있습니다.
- 4새로운 신원 생성AI에게 24단어 mnemonic과 특정 컨트랙트 버전을 가진 새로운 지갑을 생성하도록 지시할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
TON MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 TON MCP 설치
$ claude mcp add mcp -- npx -y @tonnode/mcpCursor에 TON MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@tonnode/mcp"
]
}
}
}VS Code에 TON MCP 설치
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@tonnode/mcp"
]
}
}
}VS Code CLI에 TON MCP 설치
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@tonnode/mcp"]}'Claude Desktop에 TON MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@tonnode/mcp"
]
}
}
}Codex에 TON MCP 설치
$ codex mcp add mcp -- npx -y @tonnode/mcpCodex config.toml에 TON MCP 설치
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@tonnode/mcp"]
Gemini CLI에 TON MCP 설치
$ gemini mcp add -s user mcp npx -- -y @tonnode/mcpGemini settings.json에 TON MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@tonnode/mcp"
]
}
}
}TON MCP 도구 16
README에서 감지됨get_balanceget_jetton_balanceget_jetton_infoget_transactionsget_account_staterun_get_methodparse_addressget_masterchain_infoget_swap_quotebuild_swap_txget_crosschain_quotebuild_crosschain_swap_tx
| get_balance | — | |
| get_jetton_balance | — | |
| get_jetton_info | — | |
| get_transactions | — | |
| get_account_state | — | |
| run_get_method | — | |
| parse_address | — | |
| get_masterchain_info | — | |
| get_swap_quote | — | |
| build_swap_tx | — | |
| get_crosschain_quote | — | |
| build_crosschain_swap_tx | — |
도구 16개 모두 보기도구 수 줄이기
track_crosschain_swapdisclose_crosschain_secretbuild_crosschain_refundgenerate_wallet
| track_crosschain_swap | — | |
| disclose_crosschain_secret | — | |
| build_crosschain_refund | — | |
| generate_wallet | — |
구성
TONNODE_KEYSTON_LITESERVERSOptional JSON array of private liteserver entries: [{"ip":"host","port":41000,"key":"<base64 ed25519>"}]. Defaults to the public global config.
TON_NETWORKSet to "testnet" to use the testnet global config.
| 이름 | 설명 | 유형 |
|---|---|---|
| TONNODE_KEYS | — | |
| TON_LITESERVERS | Optional JSON array of private liteserver entries: [{"ip":"host","port":41000,"key":"<base64 ed25519>"}]. Defaults to the public global config. | |
| TON_NETWORK | Set to "testnet" to use the testnet global config. |
자동 검사
2026년 11월 13일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용통과
- 파괴적인 도구에 라벨 표시됨통과
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음통과
README
GitHub에서 보기@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, a mempool stream and a REST API (early access, on request).
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. Ready-made configs for every client — plus programmatic Node.js usage — live in examples/.
Tools
Naming note: the native coin was renamed from Toncoin to GRAM in June 2026; the network itself is still called TON. Tool outputs use
*_gramfields.
| Tool | What it does | Typical question |
|---|---|---|
get_balance |
GRAM balance of an address | "How much GRAM does EQ… hold?" |
get_jetton_balance |
Jetton/token balance (USDT and any TEP-74 token) | "How much USDT is on this wallet?" |
get_jetton_info |
Token metadata: name, symbol, decimals, supply | "What are this jetton's decimals?" |
get_transactions |
Recent transactions: values, senders, fees | "Did my payment arrive?" |
get_account_state |
Status, deployment flags, last-tx pointer | "Is this contract deployed?" |
run_get_method |
Read-only get-methods on contracts | "Call get_jetton_data on this master" |
parse_address |
Convert/validate EQ…/UQ…/raw forms, offline | "Are these two addresses the same?" |
get_masterchain_info |
Masterchain head: seqno, shard, hashes | "Is the network (or my endpoint) alive?" |
get_swap_quote |
Firm DEX swap quote (GRAM ⇄ any jetton) via Omniston | "How much USDT for 100 GRAM right now?" |
build_swap_tx |
Unsigned, TonConnect-ready swap transaction | "Prepare that swap for my wallet to sign" |
get_crosschain_quote |
Quote TON → Ethereum/Arbitrum/Base/BNB/Polygon/Avalanche | "How much USDT on Ethereum for my TON USDT?" |
build_crosschain_swap_tx |
Unsigned HTLC escrow transaction + its secret | "Start that cross-chain swap" |
track_crosschain_swap |
Live phases of a cross-chain trade on both chains | "Did the resolver lock my USDT on Ethereum?" |
disclose_crosschain_secret |
Reveal the secret — atomically settles both sides | "Complete the swap" |
build_crosschain_refund |
Unsigned cancellation that reclaims escrowed funds | "The trade stalled — get my money back" |
generate_wallet |
Mint a fresh TON wallet (mnemonic + keys + address) | "Create a wallet for my agent to use" |
Wallet generation
generate_wallet mints a brand-new wallet — a 24-word mnemonic, its ed25519 keypair and the address for the chosen contract version (v4 default, plus v3r2, v5r1 and highload_v3 for mass payouts). The v3r2/v4/v5r1 addresses come from @ton/ton's canonical contracts; highload_v3 is derived from the official contract code and cross-checked against a maintained reference implementation.
⚠️ This returns secret key material. In hosted mode the keys are generated on the server and returned over TLS — treat every generated wallet as hot: fine for programmatic/ephemeral use, but move any meaningful balance to cold storage, and keep the response out of logs and shared transcripts. The server never stores or logs the mnemonic or private key (only the public address). Operators can set
TONNODE_DISABLE_WALLET_GEN=1to remove the tool entirely.
Swaps — agents that can actually trade
get_swap_quote and build_swap_tx are powered by Omniston, STON.fi's RFQ protocol aggregating STON.fi and DeDust liquidity. No API key needed.
The flow is strictly non-custodial — the server never sees a private key, never signs and never broadcasts:
get_swap_quotelocks a firm quote (amounts in raw indivisible units; the answer includes the slippage floor, price impact, gas budget and DEX route).build_swap_txturns the quote into unsigned messages in exactly the shapetonConnectUi.sendTransaction()expects — signing and sending stay with the wallet owner.
Quotes expire in about a minute, so build promptly. Omniston emulates the transfer while building: if the wallet doesn't hold the input amount, the build fails up front instead of burning gas on-chain.
Cross-chain
The *_crosschain_* tools take the same idea across blockchains: pay in GRAM or any TON jetton, receive USDT/USDC/native coins on Ethereum, Arbitrum, Base, BNB, Polygon or Avalanche — settled through Omniston's atomic HTLC escrow, typically in well under a minute. TON is always the source chain (the signer is a TON wallet).
The agent drives the full atomic-swap lifecycle: quote → build (the tool generates the HTLC secret and hands it to the caller — the server keeps nothing) → sign & send → track both chains → disclose the secret to settle, or build a refund if the trade stalls. At no point can the server, the resolver or anyone else redirect the funds: the secret only completes the trade as quoted, and an unfilled escrow is always reclaimable by the owner wallet.
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
Want a ready-made hosted endpoint instead of running your own? Keys for mcp.tonnode.io are issued at tonnode.io/mcp. Clients connect without installing anything:
{
"mcpServers": {
"ton": {
"url": "https://your-host/mcp",
"headers": { "Authorization": "Bearer tn_live_abc" }
}
}
}
Requests are authenticated with Bearer keys and rate-limited per key (RATE_LIMIT_RPM, default 300). Besides Authorization: Bearer <key>, the server accepts a bare Authorization: <key> and X-API-Key: <key> — for gateways (e.g. Smithery) that reserve the Authorization header for themselves. Keys come from either TONNODE_KEYS (comma-separated, fixed) or TONNODE_KEYS_FILE — a JSON array of {"key", "label"?, "rpm"?, "expires"?} that is hot-reloaded on change and on SIGHUP: add or revoke customer keys with no restart, per-key rate limits, and self-expiring keys for subscription plans. A revoked key's live sessions are closed immediately. GLOBAL_RATE_LIMIT_RPM adds a total ceiling across all keys to protect the backend liteserver. 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 keys the server refuses to start; set TONNODE_ALLOW_OPEN=1 to explicitly run keyless behind your own firewall. GET /healthz for monitoring, deploy/tonnode-keys.sh for key management.
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 (simple, fixed) |
TONNODE_KEYS_FILE |
HTTP mode: JSON key file with labels, per-key rpm, expires — hot-reloaded |
HOST |
HTTP mode: bind address (default 127.0.0.1) |
PORT |
HTTP mode: listen port (default 8808) |
RATE_LIMIT_RPM |
HTTP mode: default requests per minute per key (default 300) |
GLOBAL_RATE_LIMIT_RPM |
HTTP mode: total ceiling across all keys (default off) |
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) |
OMNISTON_API_URL |
Swap tools: alternative Omniston WebSocket endpoint (default wss://omni-ws.ston.fi) |
OMNISTON_INTEGRATOR_ADDRESS / OMNISTON_INTEGRATOR_FEE_BPS |
Swap tools: optional integrator revenue share in bps of the output — always visible to the caller as integrator_fee_units in every quote (default off) |
TONNODE_DISABLE_WALLET_GEN |
Set to 1 to remove the generate_wallet tool (e.g. on a shared hosted endpoint where you don't want key material generated server-side) |
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 your own rate limit and archive history, point TON_LITESERVERS at a private liteserver — a keypair and a global.config.json from the console, paid from a balance funded in GRAM or USDT. How the config file, ADNL keys and archive routing work is covered in the TON Liteserver guide.
Mempool stream
Pending messages are not exposed through this MCP server — none of the tools above read the mempool. TONNode offers the mempool as a separate WebSocket feed at wss://mempool.tonnode.io/v1/stream: one JSON object per external message as TONNode's node receives it from the public overlay, before it lands in a block, with filters by destination wallet, op code or DEX pool and a short replay after a reconnect. Plans are priced by the number of simultaneous connections on one key. Coverage is partial — the node sees only what reaches it over the overlay, and no completeness or speed figures are promised — and messages sent through TONNode's liteservers usually do not appear in it (the node does not publish its own broadcasts; a copy relayed back by other nodes showed up for 2 of 20 sends in a test on 8 October 2026). Protocol, keys and plans: tonnode.io/en/docs/mempool.
License
MIT © TONNode
TON MCP 질문
TON MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add mcp -- npx -y @tonnode/mcp를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
TON MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
TON MCP는 어떤 도구를 제공하나요?
16개 도구를 제공합니다. 예: get_balance, get_jetton_balance, get_jetton_info, get_transactions, get_account_state.
TON MCP server로 AI 에이전트가 무엇을 할 수 있나요?
TON liteserver를 통해 GRAM 및 jetton 잔액, 계정 상태, 트랜잭션 내역, 컨트랙트 get-method를 조회할 수 있으며, 서명되지 않은 트랜잭션 생성을 위한 스왑 견적을 가져올 수 있습니다.
서버가 스왑 트랜잭션에 서명하거나 브로드캐스트하나요?
아니요. 서버는 서명되지 않은 TonConnect 준비 메시지를 반환하며, 서명 및 전송은 지갑 소유자가 직접 수행합니다.
Claude Desktop 또는 Cursor에 어떻게 연결하나요?
MCP 클라이언트 설정에 npx -y @tonnode/mcp를 추가하십시오. 기본적으로 공개 글로벌 설정을 통해 TON 메인넷에 연결됩니다.
hosted HTTP 모드는 어떻게 인증하나요?
Authorization 또는 X-API-Key 헤더를 통해 전달되는 Bearer API key를 사용하며, 키별로 rate limiting이 적용됩니다.
generate_wallet로 어떤 지갑을 생성할 수 있나요?
v4, v3r2, v5r1 또는 highload_v3 컨트랙트 버전에 대한 24단어 mnemonic, ed25519 키 쌍 및 주소를 생성합니다.