@tonnode/mcp

English version

MCP-сервер, который даёт ИИ-агентам прямой доступ к The Open Network (TON) через лайтсерверы — без HTTP-шлюзов посередине. Балансы, состояние аккаунтов, история транзакций и get-методы контрактов по нативному протоколу ADNL.

Разработан TONNode — приватные лайтсерверы TON, архивные ноды, мемпул-стрим и индексированный API.

Быстрый старт

Добавьте в Claude Desktop, Claude Code, ChatGPT, Cursor, Codex или любой другой MCP-клиент:

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

Это вся интеграция. По умолчанию сервер подключается к мейннету TON через публичный глобальный конфиг. Готовые конфиги для всех клиентов — плюс программное использование из Node.js — в examples/.

Инструменты

О названиях: в июне 2026 нативная монета переименована из Toncoin в GRAM; сама сеть по-прежнему называется TON. В ответах инструментов используются поля *_gram.

| Инструмент | Что делает | Типичный вопрос | |---|---|---| | get_balance | Баланс GRAM по адресу | «Сколько GRAM на EQ…?» | | get_jetton_balance | Баланс жетона/токена (USDT и любой TEP-74) | «Сколько USDT на этом кошельке?» | | get_jetton_info | Метаданные токена: имя, символ, decimals, эмиссия | «Сколько decimals у этого жетона?» | | get_transactions | Последние транзакции: суммы, отправители, комиссии | «Пришёл ли мой платёж?» | | get_account_state | Статус, флаги деплоя, указатель последней транзакции | «Этот контракт задеплоен?» | | run_get_method | Read-only get-методы контрактов | «Вызови get_jetton_data у мастера» | | parse_address | Конвертация/проверка форм EQ…/UQ…/raw, офлайн | «Это один и тот же адрес?» | | get_masterchain_info | Вершина мастерчейна: seqno, шард, хэши | «Жива ли сеть (и мой эндпоинт)?» | | get_swap_quote | Твёрдая DEX-котировка (GRAM ⇄ любой жетон) через Omniston | «Сколько USDT дадут за 100 GRAM прямо сейчас?» | | build_swap_tx | Неподписанная swap-транзакция, готовая для TonConnect | «Собери этот своп — кошелёк сам подпишет» | | get_crosschain_quote | Котировка TON → Ethereum/Arbitrum/Base/BNB/Polygon/Avalanche | «Сколько USDT на Ethereum за мой TON-USDT?» | | build_crosschain_swap_tx | Неподписанная HTLC-эскроу транзакция + её секрет | «Начни кроссчейн-своп» | | track_crosschain_swap | Фазы кроссчейн-сделки на обеих сетях | «Резолвер уже залочил мой USDT в Ethereum?» | | 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 выводится из официального кода контракта и сверен с поддерживаемой референс-реализацией.

⚠️ Инструмент возвращает секретный ключевой материал. В hosted-режиме ключи генерируются на сервере и передаются по TLS — считай любой такой кошелёк горячим: годится для программного/временного использования, но крупные суммы переводи в холодное хранилище, а ответ держи вне логов и общих переписок. Сервер никогда не сохраняет и не логирует мнемонику или приватный ключ (только публичный адрес). Оператор может задать TONNODE_DISABLE_WALLET_GEN=1, чтобы полностью убрать инструмент.

Свапы — агенты, которые умеют торговать

get_swap_quote и build_swap_tx работают через Omniston — RFQ-протокол STON.fi, агрегирующий ликвидность STON.fi и DeDust. API-ключ не нужен.

Флоу строго некастодиальный — сервер никогда не видит приватный ключ, ничего не подписывает и не отправляет:

1. get_swap_quote фиксирует твёрдую котировку (суммы в неделимых единицах; в ответе — минимум с учётом слиппеджа, влияние на цену, бюджет газа и маршрут по DEX).
2. build_swap_tx превращает котировку в неподписанные сообщения ровно той формы, которую ждёт tonConnectUi.sendTransaction() — подпись и отправка остаются за владельцем кошелька.

Котировка живёт около минуты — собирайте транзакцию сразу. При сборке Omniston эмулирует перевод: если на кошельке нет входной суммы, сборка упадёт заранее, а не сожжёт газ он-чейн.

Кроссчейн

Инструменты *_crosschain_* переносят ту же идею между блокчейнами: платишь в GRAM или любом жетоне TON — получаешь USDT/USDC/нативные монеты в Ethereum, Arbitrum, Base, BNB, Polygon или Avalanche через атомарный HTLC-эскроу Omniston, обычно меньше чем за минуту. TON всегда исходная сеть (подписывает TON-кошелёк).

Агент ведёт полный цикл атомарного свапа: котировка → сборка (инструмент генерирует HTLC-секрет и отдаёт его вызывающему — сервер ничего не хранит) → подпись и отправка → трекинг обеих сетей → раскрытие секрета для расчёта, либо refund, если сделка зависла. Ни сервер, ни резолвер, ни кто-либо ещё не может перенаправить средства: секрет лишь завершает сделку по котировке, а незаполненный эскроу всегда возвращается кошельку-владельцу.

Hosted / self-hosted HTTP-режим

В пакете есть и Streamable-HTTP-режим для удалённого развёртывания (именно он работает на mcp.tonnode.io):

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

Нужен готовый hosted-эндпоинт вместо собственного? Ключи для 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> — для шлюзов (например, Smithery), которые резервируют заголовок Authorization под себя. Ключи берутся либо из TONNODE_KEYS (через запятую, фиксированный список), либо из TONNODE_KEYS_FILE — JSON-массива {"key", "label"?, "rpm"?, "expires"?}, который горячо перечитывается при изменении файла и по SIGHUP: добавляйте и отзывайте клиентские ключи без рестарта, задавайте индивидуальные лимиты и срок действия ключей для тарифов по подписке. Живые сессии отозванного ключа закрываются немедленно. GLOBAL_RATE_LIMIT_RPM добавляет общий потолок по всем ключам, защищая бэкенд-лайтсервер. Сессии приватны для открывшего их ключа, простаивающие закрываются после 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 | Свои лайтсерверы вместо публичного конфига: [{"ip":"1.2.3.4","port":40004,"key":"<base64 ed25519>"}] | | TON_CONFIG_URL | Альтернативный URL глобального конфига | | TON_NETWORK=testnet | Использовать тестнет (или флаг --testnet) | | TONNODE_KEYS | HTTP-режим: Bearer-ключи через запятую (просто, фиксированный список) | | TONNODE_KEYS_FILE | HTTP-режим: JSON-файл ключей с label, индивидуальными rpm и expires — горячая перезагрузка | | HOST | HTTP-режим: адрес для прослушивания (по умолчанию 127.0.0.1) | | PORT | HTTP-режим: порт (по умолчанию 8808) | | RATE_LIMIT_RPM | HTTP-режим: базовый лимит запросов в минуту на ключ (по умолчанию 300) | | GLOBAL_RATE_LIMIT_RPM | HTTP-режим: общий потолок по всем ключам (по умолчанию выключен) | | SESSION_TTL_MIN | HTTP-режим: минут простоя до закрытия сессии (по умолчанию 30) | | MAX_SESSIONS / MAX_SESSIONS_PER_KEY | HTTP-режим: лимиты одновременных сессий (по умолчанию 500 / 50) | | OMNISTON_API_URL | Свапы: альтернативный WebSocket-эндпоинт Omniston (по умолчанию wss://omni-ws.ston.fi) | | OMNISTON_INTEGRATOR_ADDRESS / OMNISTON_INTEGRATOR_FEE_BPS | Свапы: необязательная интеграторская комиссия в bps от выхода — всегда видна вызывающему как integrator_fee_units в каждой котировке (по умолчанию выключена) | | TONNODE_DISABLE_WALLET_GEN | Задай 1, чтобы убрать инструмент generate_wallet (например, на общем hosted-эндпоинте, где не нужно генерировать ключи на сервере) |

О публичных лайтсерверах

Лайтсерверы из публичного конфига — общие, с жёсткими лимитами и без глубокой истории: get_transactions дальше последних блоков ответит lt not in db. Агенты к тому же запрашивают данные пачками, и публичные шлюзы это режут.

Для гарантированной пропускной способности, архивной глубины и мемпул-стрима на уровне ноды укажите в TON_LITESERVERS приватный эндпоинт — tonnode.io выдаёт его за минуту, оплата в TON.

Лицензия

MIT © TONNode