Tgcloud MCP Server

tgcloud-mcp — MCP-сервер для Telegram serverless bots

⚠️ Неофициальный проект. Это community-инструмент (автор @sdamarketing), не аффилированный с Telegram. Официальный инструмент платформы — CLI @tgcloud/cli; tgcloud-mcp лишь удобно оборачивает его в MCP. Политика безопасности и модель угроз: SECURITY.md.

Учит AI-ассистента управлять serverless-ботами Telegram (core.telegram.org/bots/serverless): вы говорите ассистенту «создай бота», «задеплой», «покажи статус вебхука» — а он выполняет это через tgcloud CLI, не трогая терминал руками.

Работает с любым MCP-клиентом: opencode, Claude Code, Claude Desktop, Cursor, VS Code (Copilot), Windsurf, Zed.

Что умеет

14 инструментов — полный срез команд tgcloud CLI:

Плюс MCP-ресурсы tgcloud://docs/* — встроенная справка платформы (структура проекта, правила импортов, sdk/db, sdk/api, sdk/fetch, CLI).

Безопасность

• Деструктивное требует подтверждения. reset, push --force, webhook sync --drop-pending и применение миграций отказываются работать без confirm: true — ассистент сначала покажет, что будет изменено, и спросит согласие.
• Токены не утекают. Токен бота передаётся в CLI через stdin и маскируется во всех выводах — ассистент никогда его не видит в ответах инструментов.

Установка

Рекомендуемый путь — npm-пакет (публикуется через OIDC trusted publishing c Sigstore provenance — цепочку можно проверить). curl | bash есть для удобства, но это выполнение удалённого скрипта: сначала прочитайте его (уберите | bash), или используйте npm.

Требуется Node.js 20+ (CLI платформы tgcloud требует 18+).

Из npm:

npm install -g tgcloud-mcp
tgcloud-mcp setup     # мастер: настройка MCP-клиента

В одну команду (macOS / Linux / WSL) — клон в ~/.tgcloud-mcp + мастер:

curl -fsSL https://raw.githubusercontent.com/sdamarketing/tgcloud_mcp/main/install.sh | bash

Docker:

docker run -i --rm ghcr.io/sdamarketing/tgcloud-mcp

Из исходников:

git clone https://github.com/sdamarketing/tgcloud_mcp.git
cd tgcloud_mcp
npm install && npm test    # build + smoke + e2e

Подробно (токены, клиенты, переменные, решение проблем) — docs/SETUP.md.

Подключение к агенту

Конфиг MCP-клиента (пример для opencode / Claude Code / Cursor — формат mcpServers одинаковый):

{
  "mcpServers": {
    "tgcloud": {
      "command": "tgcloud-mcp"
    }
  }
}

Переменные окружения (опционально):

Пример диалога

Вы: создай эхо-бота в ~/bots/echo
Агент: create_project → login_bot (спросит токен у @BotFather) → правит handlers/message.js → push → webhook_sync — бот жив.
Вы: напиши тест и проверь
Агент: run_handler с payload { chat: { id: 1 }, text: "hi" } — показывает вывод и логи.

Кукбук

📗 Serverless-бот с мини-аппом за вечер — пошаговый рецепт на примере реального бота «Дневник обучения»: скаффолд, токены, база и миграции, inline-кнопки, Mini App с endpoints. Самоснятые форматы CLI и грабли включены.

Скилл для агентов

В репозитории лежит скилл skills/tgcloud — процедурные знания для агента: структура проекта, правила импортов, рецепты (create → login → run → push), guardrails платформы. Установка во все обнаруженные агенты:

npx skills add sdamarketing/tgcloud_mcp

Структура репозитория

src/
├─ index.ts            # сервер, регистрация инструментов/ресурсов
├─ config.ts           # env-конфиг
├─ runner.ts           # запуск tgcloud CLI: spawn, таймауты, маскировка секретов
├─ utils.ts            # runTool/result-хелперы, dangerTool (confirm-guard)
└─ tools/              # lifecycle, sync, data, webhook
resources/docs/        # справка платформы → MCP-ресурсы
skills/tgcloud/        # скилл для AI-агентов
scripts/smoke-test.mjs # stdio smoke-тест

Лицензия

MIT