tgcloud — Telegram serverless bots

io.github.sdamarketingv0.2.1更新于 Oct 9, 2026

MCP server for Telegram serverless bots: lifecycle, deploys, migrations, webhooks via tgcloud CLI

已验证STDIO仅桌面Cloud & InfrastructureDeveloper ToolsCommunication & Collaboration

概览

AI 生成的概览

让助手通过 tgcloud CLI 创建、部署和管理 Telegram 无服务器机器人，包括 Webhook 诊断和数据库迁移。

功能
把 tgcloud CLI 封装为 14 个工具，覆盖机器人生命周期：create_project、init_project、login_bot 和 add_module 用于搭建项目并绑定机器人令牌；status、diff、push、pull、fetch 和 reset 用于查看改动并与云端同步；run_handler 和 migrate 用于在本地带日志运行处理器、以 dry-run 方式执行数据库迁移；webhook_status 和 webhook_sync 用于诊断和重设 Webhook。此外还提供 tgcloud://docs/* 资源作为平台参考文档。
适用场景
适合在开发或运维 Telegram 无服务器机器人时使用：让助手搭建项目、部署改动、运行处理器做测试，或排查因 Webhook 配置导致的机器人无响应问题，而不必自己输入 tgcloud 命令。
运行要求
以 stdio 方式在本地运行，需要 Node.js 20+（平台 CLI 需要 18+）。可从 npm 安装 tgcloud-mcp，或运行 ghcr.io/sdamarketing/tgcloud-mcp:0.2.1 容器。可用 TGCLOUD_TOKEN 密钥提供来自 @BotFather 的 tgcloud CLI 访问令牌，替代登录流程；可选变量 TGCLOUD_CLI、TGCLOUD_CLI_ARGS 和 TGCLOUD_TIMEOUT_MS 用于调整 CLI 调用方式。需要网络访问以连接 tgcloud 平台。
安装前请注意
该服务器持有机器人访问令牌（TGCLOUD_TOKEN），并把机器人令牌传给 CLI；README 称令牌通过 stdin 传递并在输出中做掩码处理。破坏性操作——reset、push --force、webhook sync --drop-pending 以及应用迁移——据称需要 confirm: true，但它们仍会修改或删除云端的机器人状态，批准前应先确认助手将要执行的内容。

安装

在 SourceWeft 中

  1. 打开 控制台中的 tgcloud — Telegram serverless bots，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

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

[CI] [npm] [skills.sh] [ghcr]

Учит 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:

КатегорияИнструментыЧто делают
Жизненный циклcreate_project, init_project, login_bot, add_moduleскаффолд проекта, привязка бота по токену @BotFather, новые хендлеры и lib-модули
Синхронизацияstatus, diff, push, pull, fetch, resetпросмотр изменений, атомарный деплой, синхронизация с облаком
Данныеrun_handler, migrateпрогон хендлера без деплоя (с логами), миграции БД с dry-run
Вебхукwebhook_status, webhook_syncдиагностика «бот молчит», перенастройка вебхука

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

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

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

Установка

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

Из npm:

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

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

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

Docker:

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

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

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

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

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

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

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

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

ПеременнаяПо умолчаниюНазначение
TGCLOUD_CLInpxКоманда запуска CLI (можно указать глобально установленный tgcloud)
TGCLOUD_CLI_ARGStgcloudАргументы-префикс перед субкомандой
TGCLOUD_TIMEOUT_MS120000Таймаут одной команды CLI

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

Вы: создай эхо-бота в ~/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 платформы. Установка во все обнаруженные агенты:

bash
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, webhookresources/docs/        # справка платформы → MCP-ресурсыskills/tgcloud/        # скилл для AI-агентовscripts/smoke-test.mjs # stdio smoke-тест

Лицензия

MIT

来源：README.md，提交 45a79a6

工具

0
工具元数据尚未被收录。

版本历史

1
  1. v0.2.1最新Oct 9, 2026