TONNode — TON blockchain access

@tonnode/mcp

ロシア語版

AI エージェントに The Open Network (TON) への直接的な liteserver アクセスを提供する MCP サーバーです。間に HTTP ゲートウェイを挟みません。残高、アカウント状態、トランザクション履歴、コントラクトの get メソッドを、TON ネイティブの ADNL プロトコル経由で扱います。

開発は TONNode — プライベート TON liteserver、アーカイブノード、mempool ストリーム、REST API(早期アクセス、申請ベース)。

クイックスタート

Claude Desktop、Claude Code、ChatGPT、Cursor、Codex、その他任意の MCP クライアントに追加します:

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

統合はこれだけです。サーバーはデフォルトで公開グローバル設定を介して TON メインネットに接続します。各クライアント向けの既成の設定ファイル、およびプログラムによる Node.js での利用方法は examples/ にあります。

ツール

命名に関する注意: ネイティブコインは 2026 年 6 月に Toncoin から GRAM に改名されましたが、ネットワーク自体は今も TON と呼ばれています。ツールの出力では *_gram フィールドが使われます。

ツール	機能	典型的な質問
get_balance	アドレスの GRAM 残高	「EQ… は GRAM をいくら保有していますか?」
get_jetton_balance	Jetton/トークン残高(USDT および任意の TEP-74 トークン)	「このウォレットには USDT がいくらありますか?」
get_jetton_info	トークンのメタデータ: 名前、シンボル、decimals、供給量	「この jetton の decimals はいくつですか?」
get_transactions	最近のトランザクション: 金額、送信者、手数料	「支払いは届きましたか?」
get_account_state	ステータス、デプロイフラグ、最終トランザクションポインタ	「このコントラクトはデプロイされていますか?」
run_get_method	コントラクト上の読み取り専用 get メソッド	「このマスターで get_jetton_data を呼び出してください」
parse_address	EQ…/UQ…/raw 形式の変換・検証(オフライン)	「この 2 つのアドレスは同じですか?」
get_masterchain_info	マスターチェーンの先頭: seqno、シャード、ハッシュ	「ネットワーク(または自分のエンドポイント)は生きていますか?」
get_swap_quote	Omniston 経由の確定 DEX スワップ見積もり(GRAM ⇄ 任意の jetton)	「今 100 GRAM は USDT でいくらですか?」
build_swap_tx	未署名の TonConnect 対応スワップトランザクション	「そのスワップをウォレットで署名できるように準備してください」
get_crosschain_quote	TON → Ethereum/Arbitrum/Base/BNB/Polygon/Avalanche の見積もり	「私の TON USDT は Ethereum 上の USDT でいくらですか?」
build_crosschain_swap_tx	未署名の HTLC エスクロートランザクションとそのシークレット	「そのクロスチェーンスワップを開始してください」
track_crosschain_swap	両チェーンにまたがるクロスチェーン取引のライブフェーズ	「リゾルバーは Ethereum 上で私の USDT をロックしましたか?」
disclose_crosschain_secret	シークレットを公開 — 両側をアトミックに決済	「スワップを完了してください」
build_crosschain_refund	エスクローされた資金を取り戻す未署名のキャンセル	「取引が行き詰まりました — お金を取り戻してください」
generate_wallet	新しい TON ウォレットを作成(ニーモニック + 鍵 + アドレス)	「エージェントが使うウォレットを作成してください」

ウォレット生成

generate_wallet は真新しいウォレットを作成します — 24 単語のニーモニック、その ed25519 鍵ペア、および選択したコントラクトバージョンのアドレスです(デフォルトは v4、ほかに一括支払い向けの v3r2、v5r1、highload_v3)。v3r2/v4/v5r1 のアドレスは @ton/ton の正規コントラクトから取得し、highload_v3 は公式のコントラクトコードから導出し、保守されているリファレンス実装と照合して検証しています。

⚠️ これは秘密鍵の素材を返します。 ホストモードでは鍵はサーバー上で生成され、TLS 経由で返されます — 生成されたウォレットはすべて ホット として扱ってください。プログラムによる一時的な利用には問題ありませんが、意味のある残高はコールドストレージに移し、レスポンスをログや共有されるトランスクリプトに残さないでください。サーバーはニーモニックや秘密鍵を保存もログ記録もしません(公開アドレスのみ)。運用者は TONNODE_DISABLE_WALLET_GEN=1 を設定することで、このツールを完全に無効化できます。

スワップ — 実際に取引できるエージェント

get_swap_quote と build_swap_tx は Omniston によって提供されています。これは STON.fi の RFQ プロトコルで、STON.fi と DeDust の流動性を集約します。API キーは不要です。

このフローは厳密にノンカストディアルです — サーバーが秘密鍵を目にすることはなく、署名もブロードキャストも行いません:

1. get_swap_quote は確定クォートをロックします（金額は分割不可能な生の単位で、回答にはスリッページ下限、価格インパクト、ガスバジェット、DEX ルートが含まれます）。
2. build_swap_tx はクォートを、tonConnectUi.sendTransaction() が期待するまさにその形式の未署名メッセージに変換します — 署名と送信はウォレットの所有者が行います。

クォートは約 1 分で失効するため、速やかにビルドしてください。Omniston はビルド時に転送をエミュレートします: ウォレットが入力額を保有していなければ、オンチェーンでガスを消費する代わりに、ビルドが事前に失敗します。

クロスチェーン

*_crosschain_* ツールは同じ考え方をブロックチェーンをまたいで適用します: GRAM または任意の TON ジェットンで支払い、Ethereum、Arbitrum、Base、BNB、Polygon、Avalanche で USDT/USDC/ネイティブコインを受け取ります — Omniston のアトミック HTLC エスクローを通じて決済され、通常は 1 分をはるかに下回ります。TON は常にソースチェーンです（署名者は TON ウォレットです）。

エージェントはアトミックスワップのライフサイクル全体を駆動します: クォート → ビルド（ツールが HTLC シークレットを生成し、呼び出し元に渡します — サーバーは何も保持しません）→ 署名して送信 → 両方のチェーンを追跡 → シークレットを開示して決済、または取引が停滞した場合は返金をビルド。いかなる時点でも、サーバー、リゾルバー、その他の誰も資金を流用することはできません: シークレットはクォートどおりに取引を完了させるだけであり、未充填のエスクローは常に所有者ウォレットが回収できます。

ホスト型 / セルフホスト型 HTTP モード

このパッケージには、リモートデプロイ用の Streamable-HTTP エントリも同梱されています（これが mcp.tonnode.io を動かしているものです）:

TONNODE_KEYS=tn_live_abc,tn_live_def PORT=8808 npx -y @tonnode/mcp --http

自分で運用する代わりに、すぐ使えるホスト型エンドポイントが欲しいですか？ mcp.tonnode.io のキーは tonnode.io/mcp で発行されます。クライアントは何もインストールせずに接続できます:

{
  "mcpServers": {
    "ton": {
      "url": "https://your-host/mcp",
      "headers": { "Authorization": "Bearer tn_live_abc" }
    }
  }
}

リクエストは Bearer キーで認証され、キーごとにレート制限されます（RATE_LIMIT_RPM、デフォルト 300）。Authorization: Bearer <key> に加えて、サーバーは素の Authorization: <key> と X-API-Key: <key> も受け付けます — これは Authorization ヘッダーを自らに予約するゲートウェイ（例: Smithery）向けです。キーは TONNODE_KEYS（カンマ区切り、固定）または TONNODE_KEYS_FILE のいずれかから取得します — 後者は {"key", "label"?, "rpm"?, "expires"?} の JSON 配列で、変更時および SIGHUP 時にホットリロードされます: 再起動なしで顧客キーの追加や失効、キーごとのレート制限、サブスクリプションプラン向けの自動失効キーが可能です。失効したキーのライブセッションは即座に閉じられます。GLOBAL_RATE_LIMIT_RPM は、バックエンドの liteserver を保護するために全キー合計の上限を追加します。セッションはそれを開いたキーにプライベートであり、アイドルセッションは SESSION_TTL_MIN（デフォルト 30 分）後に掃除され、同時セッション数はキーごとおよび全体で上限が設けられます。キーがない場合、サーバーは起動を拒否します。独自のファイアウォールの背後で明示的にキーなしで運用するには TONNODE_ALLOW_OPEN=1 を設定してください。監視には GET /healthz、キー管理には deploy/tonnode-keys.sh をご利用ください。

サーバーはデフォルトで 127.0.0.1 にバインドします — 前面に TLS リバースプロキシ（Caddy、nginx）を置き、プロキシが別のマシンで動作する場合にのみ HOST=0.0.0.0 を設定してください。すぐ使える systemd + Caddy の設定は deploy/ にあります。

設定

環境変数	意味
TON_LITESERVERS	公開設定の代わりに独自の liteserver を使用します: [{"ip":"1.2.3.4","port":40004,"key":"<base64 ed25519>"}]
TON_CONFIG_URL	代替のグローバル設定 URL
TON_NETWORK=testnet	testnet 設定を使用します (または --testnet を渡します)
TONNODE_KEYS	HTTP モード: カンマ区切りの Bearer API キー (シンプル、固定)
TONNODE_KEYS_FILE	HTTP モード: ラベル付きの JSON キーファイル、キーごとの rpm、expires — ホットリロードされます
HOST	HTTP モード: バインドアドレス (デフォルト 127.0.0.1)
PORT	HTTP モード: 待ち受けポート (デフォルト 8808)
RATE_LIMIT_RPM	HTTP モード: キーごとの 1 分あたりのデフォルトリクエスト数 (デフォルト 300)
GLOBAL_RATE_LIMIT_RPM	HTTP モード: 全キー合計の上限 (デフォルトは無効)
SESSION_TTL_MIN	HTTP モード: セッションが破棄されるまでのアイドル分数 (デフォルト 30)
MAX_SESSIONS / MAX_SESSIONS_PER_KEY	HTTP モード: 同時セッション数の上限 (デフォルト 500 / 50)
OMNISTON_API_URL	スワップツール: 代替の Omniston WebSocket エンドポイント (デフォルト wss://omni-ws.ston.fi)
OMNISTON_INTEGRATOR_ADDRESS / OMNISTON_INTEGRATOR_FEE_BPS	スワップツール: 出力に対する integrator の収益分配を bps で任意指定 — すべての quote で integrator_fee_units として呼び出し元に常に表示されます (デフォルトは無効)
TONNODE_DISABLE_WALLET_GEN	1 に設定すると generate_wallet ツールを削除します (例: サーバー側でキーマテリアルを生成したくない共有ホスト型エンドポイントの場合)

公開 liteserver に関する注意

デフォルトの公開設定の liteserver は共有されており、レート制限があり、深い履歴を保持していません — 直近のブロックを超える get_transactions は lt not in db を返します。また、エージェントはバースト的にクエリを実行する傾向があり、公開ゲートウェイはこれをスロットリングします。

独自のレート制限とアーカイブ履歴を得るには、TON_LITESERVERS をプライベート liteserver に向けてください — コンソールから取得したキーペアと global.config.json を使用し、GRAM または USDT で入金した残高から支払います。設定ファイル、ADNL キー、アーカイブルーティングの仕組みについては、TON Liteserver ガイドで説明しています。

Mempool ストリーム

保留中のメッセージは、この MCP サーバーを通じて公開されていません — 上記のどのツールも mempool を読み取りません。TONNode は mempool を wss://mempool.tonnode.io/v1/stream で別の WebSocket フィードとして提供しています。TONNode のノードが公開オーバーレイから外部メッセージを受信した時点、つまりブロックに取り込まれる前に、外部メッセージごとに 1 つの JSON オブジェクトを配信し、宛先ウォレット、オペコード、DEX プールによるフィルタと、再接続後の短いリプレイを備えています。プランは 1 つのキーでの同時接続数に応じて価格設定されています。カバレッジは部分的です — ノードはオーバーレイ経由で自身に到達したものだけを認識し、完全性や速度に関する数値は約束されていません — また、TONNode の liteserver を通じて送信されたメッセージは通常ここには現れません (ノードは自身のブロードキャストを公開しません。2026 年 10 月 8 日のテストでは、20 回の送信のうち 2 回で、他のノードによって中継されて戻ってきたコピーが確認されました)。プロトコル、キー、プランについては tonnode.io/en/docs/mempool をご覧ください。

ライセンス

MIT © TONNode