tgcloud — Telegram serverless bots

io.github.sdamarketingv0.2.1Updated Oct 9, 2026

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

VerifiedSTDIODesktop onlyCloud & InfrastructureDeveloper ToolsCommunication & Collaboration

Overview

AI-generated overview

Lets an assistant create, deploy, and manage Telegram serverless bots through the tgcloud CLI, including webhook diagnostics and database migrations.

What it does
Wraps the tgcloud CLI in 14 tools covering the bot lifecycle: create_project, init_project, login_bot and add_module scaffold a project and bind a bot token; status, diff, push, pull, fetch and reset inspect and sync changes with the cloud; run_handler and migrate run a handler locally with logs and apply database migrations with dry-run; webhook_status and webhook_sync diagnose and reconfigure webhooks. It also exposes tgcloud://docs/* resources with platform reference material.
When to use it
Useful when you build or operate Telegram serverless bots and want an assistant to scaffold projects, deploy changes, run handlers for testing, or fix a bot that has gone silent because of its webhook, instead of typing tgcloud commands yourself.
Requirements
Runs locally over stdio; Node.js 20+ is required (the platform CLI needs 18+). Installable from npm (tgcloud-mcp) or run as the ghcr.io/sdamarketing/tgcloud-mcp:0.2.1 container. A tgcloud CLI access token from @BotFather can be supplied via the TGCLOUD_TOKEN secret instead of logging in; optional variables TGCLOUD_CLI, TGCLOUD_CLI_ARGS and TGCLOUD_TIMEOUT_MS tune how the CLI is invoked. Network access is needed to reach the tgcloud platform.
Before you install
The server holds a bot access token (TGCLOUD_TOKEN) and passes bot tokens through the CLI; the README states tokens are sent via stdin and masked in outputs. Destructive operations — reset, push --force, webhook sync --drop-pending and applying migrations — are said to require confirm: true, but they still change or delete cloud-side bot state, so review what the assistant proposes before approving.

Installation

In SourceWeft

  1. Open tgcloud — Telegram serverless bots in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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

Source: README.md at commit 45a79a6

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.2.1LatestOct 9, 2026