@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_transactions | Последние транзакции: суммы, отправители, комиссии | «Пришёл ли мой платёж?» | | get_account_state | Статус, флаги деплоя, указатель последней транзакции | «Этот контракт задеплоен?» | | run_get_method | Read-only get-методы контрактов | «Вызови get_jetton_data у мастера» | | parse_address | Конвертация/проверка форм EQ…/UQ…/raw, офлайн | «Это один и тот же адрес?» | | get_masterchain_info | Вершина мастерчейна: seqno, шард, хэши | «Жива ли сеть (и мой эндпоинт)?» |

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

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

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

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

Лицензия

MIT © TONNode