# tgcloud — Telegram serverless bots [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/sdamarketing/tgcloud_mcp  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/tgcloud-telegram-serverless-bots

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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "tgcloud-telegram-serverless-bots": {
    "command": "npx",
    "args": ["-y","tgcloud-mcp"],
    "env": {
      "TGCLOUD_CLI": "",
      "TGCLOUD_CLI_ARGS": "",
      "TGCLOUD_TIMEOUT_MS": ""
    }
  }
}
```

**Requires environment variables:** `TGCLOUD_CLI`, `TGCLOUD_CLI_ARGS`, `TGCLOUD_TIMEOUT_MS` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What tgcloud — Telegram serverless bots does

tgcloud — Telegram serverless bots MCP server wraps the `tgcloud` CLI and exposes its bot-management workflow through MCP. It is an unofficial community project and is not affiliated with Telegram; the platform’s official command-line tool is `@tgcloud/cli`.

The server covers the main stages of a serverless bot project. Agents can scaffold or initialize projects, associate a bot using a token from BotFather, add handlers or library modules, inspect local and cloud differences, synchronize files, deploy changes, and retrieve remote state. It also supports running a handler with a payload before deployment, applying database migrations, and inspecting or updating a bot webhook.

MCP resources under `tgcloud://docs/*` provide platform reference material, including project layout, import rules, database and API SDKs, fetch support, and CLI usage.

## How it works

The MCP server starts the configured tgcloud CLI as a child process and returns its results to the connected agent. A typical workflow can create a project, log in the bot, edit a handler, run it with test input, push the project, and synchronize the webhook.

Fourteen tools are grouped into lifecycle, synchronization, data, and webhook operations. Synchronization includes status, diff, push, pull, fetch, and reset. Data operations include handler execution and migrations. Webhook tools report configuration and request synchronization with the cloud platform.

Potentially destructive actions have an explicit confirmation guard. Reset, force push, webhook synchronization with pending updates dropped, and applying migrations require `confirm: true`. Bot tokens are supplied to the CLI through standard input and masked from tool output.

## Setup and configuration

Node.js 20 or newer is required for the MCP package; the platform CLI itself requires Node.js 18 or newer. The recommended installation uses npm:

```bash
npm install -g tgcloud-mcp
tgcloud-mcp setup
```

The setup command provides a wizard for configuring an MCP client. Docker and source installation are also documented. A minimal stdio configuration uses the `tgcloud-mcp` command under an `mcpServers` entry.

The tgcloud — Telegram serverless bots MCP server can use `TGCLOUD_CLI` to select the CLI command, `TGCLOUD_CLI_ARGS` for prefix arguments, and `TGCLOUD_TIMEOUT_MS` to set the command timeout. Their documented defaults are `npx`, `tgcloud`, and `120000` respectively.

## Tools and capabilities

Use the lifecycle tools to create projects, initialize existing directories, connect a bot, and add modules. Use synchronization tools to compare local and cloud state, transfer files, deploy changes, or restore a project. `run_handler` executes a handler with supplied data and returns logs without requiring a deployment. `migrate` supports database migration workflows with a dry-run option.

Webhook status and synchronization address cases where a bot is not receiving updates. The included documentation resources help agents follow tgcloud project conventions, including use of `sdk/db`, `sdk/api`, and `sdk/fetch`.

## Limitations and notes

tgcloud — Telegram serverless bots is a community wrapper around the CLI, not an official Telegram integration. It depends on the tgcloud CLI and the availability of the target platform. The README does not describe additional Telegram API tools beyond the serverless bot workflow exposed by tgcloud.

Review destructive changes before confirming them. The repository also includes an agent skill with procedural guidance, but installing that skill is separate from installing the MCP server.

_Full upstream README: https://allmcps.com/mcp/tgcloud-telegram-serverless-bots/readme_