tgcloud — Telegram serverless bots

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

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package tgcloud-mcp

Claude Code

claude mcp add tgcloud-telegram-serverless-bots -e 'TGCLOUD_CLI=<TGCLOUD_CLI>' -e 'TGCLOUD_CLI_ARGS=<TGCLOUD_CLI_ARGS>' -e 'TGCLOUD_TIMEOUT_MS=120000' -e 'TGCLOUD_TOKEN=<your tgcloud_token>' -- npx -y tgcloud-mcp@0.3.3

JSON configuration (Claude Desktop, Cursor, VS Code)

{
    "mcpServers": {
        "tgcloud-telegram-serverless-bots": {
            "command": "npx",
            "args": [
                "-y",
                "tgcloud-mcp@0.3.3"
            ],
            "env": {
                "TGCLOUD_CLI": "<TGCLOUD_CLI>",
                "TGCLOUD_CLI_ARGS": "<TGCLOUD_CLI_ARGS>",
                "TGCLOUD_TIMEOUT_MS": "120000",
                "TGCLOUD_TOKEN": "<your tgcloud_token>"
            }
        }
    }
}

Environment variables

TGCLOUD_CLI Command that launches the tgcloud CLI (default npx; may be a proxy wrapper)
TGCLOUD_CLI_ARGS Arguments placed before the subcommand (default 'tgcloud')
TGCLOUD_TIMEOUT_MS Timeout of one CLI command, in milliseconds
TGCLOUD_TOKEN secret CLI access token from @BotFather (form app<id>:<secret>), used instead of tgcloud login

OCI package ghcr.io/sdamarketing/tgcloud-mcp:0.3.3

Claude Code

claude mcp add tgcloud-telegram-serverless-bots -e 'TGCLOUD_TOKEN=<your tgcloud_token>' -- docker run -i --rm ghcr.io/sdamarketing/tgcloud-mcp:0.3.3

JSON configuration (Claude Desktop, Cursor, VS Code)

{
    "mcpServers": {
        "tgcloud-telegram-serverless-bots": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "ghcr.io/sdamarketing/tgcloud-mcp:0.3.3"
            ],
            "env": {
                "TGCLOUD_TOKEN": "<your tgcloud_token>"
            }
        }
    }
}

Environment variables

TGCLOUD_TOKEN secret CLI access token from @BotFather (form app<id>:<secret>)

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents

tgcloud-mcp — MCP server for Telegram serverless bots
Documentation
What it does
Security
Install
Connect an agent
Example
Cookbook
Skill
Repository
License

tgcloud-mcp — MCP server for Telegram serverless bots

Русский · 中文 · العربية · Deutsch · Français

Unofficial project. This is a community tool (author @sdamarketing), not affiliated with Telegram. The platform's official tool is the @tgcloud/cli CLI. tgcloud-mcp wraps that CLI in MCP. Threat model: SECURITY.md.

Teaches an AI assistant to manage Telegram serverless bots (core.telegram.org/bots/serverless): you say "create a bot", "deploy", "show the webhook" — the assistant runs tgcloud and you do not have to drive the terminal.

Works with any MCP client: opencode, Claude Code, Claude Desktop, Cursor, VS Code (Copilot), Windsurf, Zed. The same server and skill are also one Agent Plugin (agent-plugin/) for Codex, Cursor, Copilot, Kiro, and VS Code.

Documentation

The docs site (docs7) and the Context7 index: context7.com/sdamarketing/tgcloud_mcp.

Section	Contents
Getting started	Overview, quickstart, installation
Usage	Tools, resources, security
Help	Troubleshooting, cookbook
Reference	SETUP, evening walkthrough

Other languages: ru, zh, ar, de, fr. Commands: tgcloud-mcp setup, tgcloud-mcp update, tgcloud-mcp links, tgcloud-mcp --help.

What it does

16 tools over the tgcloud CLI:

Area	Tools	What they do
Lifecycle	`create_project`, `init_project`, `login_bot`, `add_module`, `upgrade`	Scaffold, link a bot with the @BotFather token, new handlers, endpoints, and lib modules, move a pre-0.2.0 layout into `tgcloud/`
Sync	`status`, `diff`, `push`, `deploy`, `pull`, `fetch`, `reset`	See changes, atomic deploy, build-then-push for a Mini App, sync with the cloud
Data	`run_handler`, `migrate`	Run a handler or endpoint without deploying; migrations with `--dry-run`, `--safe`, `--yes`, `--local`
Webhook	`webhook_status`, `webhook_sync`	"The bot is silent", re-point the webhook

Plus MCP resources tgcloud://docs/* — platform reference in English (layout, import rules, sdk/db, sdk/api, sdk/fetch, CLI, limits).

Tool descriptions and the skill are English so the model follows one text. The assistant is told to answer you in your language. Human docs are English, Russian, Chinese, Arabic, German, and French.

Security

Destructive calls need confirmation. reset, push --force, applying upgrade, applying migrations, and webhook sync --drop-pending refuse to run without confirm: true. The assistant shows the change and asks first.
Tokens do not leak. The bot token goes to the CLI on stdin and is masked in every tool result.

Install

Prefer the npm package (published with OIDC trusted publishing and Sigstore provenance). curl | bash is convenient and runs a remote script: read it first (drop the | bash), or use npm.

Node.js 20+ (the platform CLI needs 18+).

npm:

npm install -g tgcloud-mcp
tgcloud-mcp setup

The wizard writes the MCP config. Say yes to the Agent Plugin and it copies agent-plugin/ to ~/.tgcloud-mcp/agent-plugin, into Cursor's local plugin folder, and into VS Code chat.pluginLocations.

One command (macOS / Linux / WSL):

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

Docker:

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

From source:

git clone https://github.com/sdamarketing/tgcloud_mcp.git
cd tgcloud_mcp
npm install && npm test

Details: docs/SETUP.md.

Connect an agent

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

Variable	Default	Purpose
`TGCLOUD_CLI`	`npx`	How to launch the CLI (a global `tgcloud` is fine)
`TGCLOUD_CLI_ARGS`	`tgcloud`	Arguments before the subcommand
`TGCLOUD_TIMEOUT_MS`	`120000`	Timeout of one CLI command

Example

You: create an echo bot in ~/bots/echo Agent: create_project → login_bot (asks @BotFather for the token) → edits handlers/message.js → push → webhook_sync. The bot is live. You: test it Agent: run_handler with { chat: { id: 1 }, text: "hi" } and shows the output and logs.

After front-end edits the agent calls deploy (build, then push). A plain push uploads the build folder as it is and does not run the bundler.

Cookbook

A serverless bot with a Mini App in one evening — the long walkthrough is Russian; the commands are the platform's. Short overviews: docs/cookbook.en.mdx and the ru, zh, ar, de, fr siblings.

Skill

skills/tgcloud is the procedure the agent follows: layout, imports, recipes, guardrails. The same file is agent-plugin/skills/tgcloud/SKILL.md. npm run docs:check fails if the copies diverge.

npx skills add sdamarketing/tgcloud_mcp

Repository

src/                 # server, runner, tools
resources/docs/      # platform reference → MCP resources (English)
skills/tgcloud/      # agent skill
agent-plugin/        # Agent Plugins 1.0 package (plugin.json, mcp.json, skill)
docs/                # human docs, six languages

License

MIT

Frequently asked questions

What is tgcloud — Telegram serverless bots?

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

How do I install tgcloud — Telegram serverless bots?

It runs on your machine. In Claude Code: claude mcp add tgcloud-telegram-serverless-bots -e 'TGCLOUD_CLI=<TGCLOUD_CLI>' -e 'TGCLOUD_CLI_ARGS=<TGCLOUD_CLI_ARGS>' -e 'TGCLOUD_TIMEOUT_MS=120000' -e 'TGCLOUD_TOKEN=<your tgcloud_token>' -- npx -y tgcloud-mcp@0.3.3. For other clients, paste the JSON configuration from this page into their MCP settings.

Does tgcloud — Telegram serverless bots need an API key?

Yes. It expects TGCLOUD_TOKEN, which you set in its configuration.

Is tgcloud — Telegram serverless bots open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains tgcloud — Telegram serverless bots?

It is published by sdamarketing. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.

Server details

Listed in: Official MCP Registry
Publisher: sdamarketing
Category: Cloud and DevOps
Runs: Local
GitHub stars: ★ 1
License: MIT
Language: JavaScript
Last commit: Oct 24, 2026
Open issues: 0
Version: 0.3.3
Published: Oct 15, 2026

io.github.sdamarketing/tgcloud-mcp

Similar servers

ZopDev MCP Cloud cost, inventory and governance on AWS/Azure/GCP. Read-only by default, optional s...
Edgegap Deploy and operate multiplayer game servers on Edgegap's global edge network.
Architecture Diagrams AWS, Azure and GCP architecture diagrams with official icons, reviews, Terraform and GC...
Edgible Read your Edgible applications, devices, deploy status and logs, signed in as you.
Airbrake MCP by usefulapi Read Airbrake projects, error groups, notices, deploys and stats; mute or unmute error ...
Scalingo MCP by usefulapi Manage Scalingo PaaS apps, deployments, containers, logs and env vars from your AI assi...
Increase MCP by usefulapi Read-only Increase banking observability plus one safe non-money-moving write, for AI a...
Laravel Forge MCP by usefulapi Manage Laravel Forge servers, sites, and deployments from your AI assistant.

Cloud and DevOps