# tgcloud — Telegram serverless bots (npm · tgcloud-mcp)

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

- Trust score: 83/100 (high trust)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-10-16

## Components

- npm · `tgcloud-mcp`: 83/100 (this document), [markdown](https://verifymcp.io/servers/sdamarketing-tgcloud-mcp/tgcloud-mcp.md), [page](https://verifymcp.io/servers/sdamarketing-tgcloud-mcp/tgcloud-mcp)
- oci · `ghcr.io/sdamarketing/tgcloud-mcp`: 43/100, [markdown](https://verifymcp.io/servers/sdamarketing-tgcloud-mcp/ghcr-io-sdamarketing-tgcloud-mcp.md), [page](https://verifymcp.io/servers/sdamarketing-tgcloud-mcp/ghcr-io-sdamarketing-tgcloud-mcp)

## Channel facts

- Registry: `npm`
- Package: `tgcloud-mcp`
- Version: `0.3.3`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-10-16.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - 0 of 3 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 100/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to sdamarketing/tgcloud_mcp).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 0 days ago).
  - Publishes a security disclosure policy (SECURITY.md).
- **Schema Quality & AI Usability**: 86/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (excellent).
  - Tool/resource definitions use about 2203 tokens (~100/item across 22 items; 16 tools + 6 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 7/100
  - Stability observed for 2 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Tool Safety**: 75/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - 0 of 1 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "deploy" implies "deploy" and declares no destructiveHint at all, which the MCP spec reads as destructive by default.
  - An AI judge read all 17 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### How do I install the tgcloud — Telegram serverless bots MCP server?

tgcloud — Telegram serverless bots runs locally as an npm package, launched with npx -y tgcloud-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add sdamarketing-tgcloud-mcp -- npx -y tgcloud-mcp
```

### Cursor

```json
{
  "mcpServers": {
    "sdamarketing-tgcloud-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "tgcloud-mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "sdamarketing-tgcloud-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "tgcloud-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add sdamarketing-tgcloud-mcp -- npx -y tgcloud-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sdamarketing-tgcloud-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "tgcloud-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add sdamarketing-tgcloud-mcp --command npx --arg -y --arg tgcloud-mcp
```

### Hermes

```yaml
mcp_servers:
  sdamarketing-tgcloud-mcp:
    command: "npx"
    args: ["-y", "tgcloud-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "sdamarketing-tgcloud-mcp": {
      "Transport": "stdio",
      "Command": "npx",
      "Arguments": [
        "-y",
        "tgcloud-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add sdamarketing-tgcloud-mcp -t stdio -c npx -a -y tgcloud-mcp
```

### Other

```json
{
  "mcpServers": {
    "sdamarketing-tgcloud-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "tgcloud-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-10-16 (score 83, +1)

No change was recorded against any check on this day. Stability & Change Management went from 3 to 7. That category is still filling its 30-day observation window: 1 days of observed history at the previous scan, 2 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-15 (score 82, −1)

- [security regression] Tool safety: pass → unverified
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional regression] Schema quality: 1759 → 2203
- [functional regression] Capabilities: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Schema quality: 100 → unverified
- [functional improvement] Stability: unverified → 0.03
- [functional] Destructive annotations: pass → 0
- [functional] Package version: 0.2.1 → 0.3.3
- [functional] Package version: 0.2.1 → 0.3.2

### 2026-10-14 (score 83, +33)

- [security improvement] Injection markers: unverified → pass
- [security] First check of Judged manipulation: pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] Schema quality: unverified → 100
- [functional improvement] MCP protocol: unverified → pass
- [functional] First check of Schema quality: excellent
- [functional] First check of Destructive annotations: pass
- [functional] First check of Schema quality: pass
- [functional] First check of Tool coverage: 100
- [functional] First check of Schema quality: fail

### 2026-10-12 (score 50)

First indexed and scored.

## MCP tools (16)

### `create_project` (~84 tokens)

Create a bot project

Scaffolds a serverless bot with `npm create @tgcloud/bot <name>` inside parent_dir. Needs Node.js 18+ and the npm registry. Does not overwrite existing files.

Input parameters:

- `name` (string, required): New project directory name, for example my-bot
- `parent_dir` (string, required): Absolute path of the directory that will contain the new project

### `init_project` (~108 tokens)

Initialize a project in place

Scaffolds tgcloud into an existing directory (tgcloud init, offline): tgcloud/schema.js, handlers/, endpoints/, lib/, tgcloud.jsonc, AGENTS.md, docs/tgcloud-sdk.md. In a front-end project it detects the bundler, sets static.source, and adds an npm run deploy script (build, then push) without overwriting files you already have.

Input parameters:

- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)

### `login_bot` (~159 tokens)

Link a bot to the project

Runs `tgcloud login` with a CLI access token (app<id>:<secret> from @BotFather → your bot → Serverless → CLI Access → Access token). This is NOT the Bot API token (123456:AA…). The CLI wants a TTY, so the token is written to stdin with TGCLOUD_ASSUME_TTY=1 and masked in every tool result. NEVER show the token to the user after this call. In CI, set TGCLOUD_TOKEN and skip login.

Input parameters:

- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)
- `token` (string, required): CLI access token from @BotFather (Serverless → CLI Access), form app<id>:<secret>

### `add_module` (~171 tokens)

Add a module

Scaffolds a module with `tgcloud add <target>` (tgcloud/ layout). handlers/<type> is one flat update handler (message, edited_message, callback_query, inline_query, chosen_inline_result, shipping_query, pre_checkout_query, poll, poll_answer, my_chat_member, chat_member, chat_join_request, message_reaction, channel_post, …). endpoints/<name> is a Mini App function (POST /api/<name>; identifier, not starting with a digit). lib/<path> is shared code and may be nested. Existing files are never overwritten.

Input parameters:

- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)
- `target` (string, required): Module path, for example handlers/callback_query, endpoints/getProfile, or lib/cart

### `upgrade` (~141 tokens)

Upgrade a pre-0.2.0 project layout

One-time move of schema.js, handlers/, and lib/ from the project root into tgcloud/ (tgcloud upgrade). Required before other commands on projects created before CLI 0.2.0. Keeps the bot link; nothing needs to be redeployed. dry_run defaults to true and only prints the planned moves. Applying (dry_run: false) requires confirm: true.

Input parameters:

- `confirm` (boolean): Required confirm: true when dry_run is false
- `dry_run` (boolean): true (default) — print planned moves only (--dry-run)
- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)

### `status` (~76 tokens)

Project status

Shows local changes against the deployed snapshot (tgcloud status). Offline. Also reports stray .js files inside tgcloud/ that will not deploy, Mini App static diffs, and a webhook that is out of sync with the deployed handlers.

Input parameters:

- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)

### `diff` (~47 tokens)

Line diff

Line-by-line diff of the local project against the deployed snapshot (tgcloud diff). Offline.

Input parameters:

- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)

### `push` (~224 tokens)

Deploy to the cloud

Uploads changed modules in one atomic batch (tgcloud push). Without files, mirrors the whole local module set (deletions included) and, when tgcloud.jsonc names static.source, uploads that build folder exactly as it is on disk. push never runs the bundler — after front-end edits call deploy, or the previous build goes live. A targeted push never deletes other modules and leaves static files untouched unless the target is the build folder. push does not migrate the database; it only prints pending schema changes. Adding or removing a handler can leave the webhook out of sync — follow with webhook_sync. force=true skips the revision check and requires confirm: true.

Input parameters:

- `confirm` (boolean): Required confirm: true for destructive operations (the --force flag, reset, and similar)
- `files` (array): Specific files or directories to deploy; omit to deploy every change
- `force` (boolean): Pass --force (dangerous, requires confirm: true)
- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)

### `pull` (~56 tokens)

Pull from the cloud

Makes the local project match the cloud: updates the snapshot and working files (tgcloud pull). Does not write the Mini App build folder.

Input parameters:

- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)

### `fetch` (~53 tokens)

Refresh the cloud snapshot

Updates the local snapshot of what is deployed without touching working files (tgcloud fetch). Use it before resolving a revision conflict.

Input parameters:

- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)

### `reset` (~91 tokens)

Discard local changes

DESTRUCTIVE: discards local module edits and restores the working tree from the last known cloud snapshot (tgcloud reset). Does not touch the Mini App build folder. Requires confirm: true.

Input parameters:

- `confirm` (boolean): Required confirm: true for destructive operations (the --force flag, reset, and similar)
- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)

### `deploy` (~127 tokens)

Build the Mini App and push

Runs `npm run build` when package.json has a build script, then `tgcloud push`. Use this after front-end edits: a plain push uploads static.source as it sits on disk and never runs the bundler, so it would publish a stale dist. Does not migrate the database and never passes --force. skip_build=true pushes without building. If there is no build script, only push runs.

Input parameters:

- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)
- `skip_build` (boolean): true — skip npm run build and only push

### `run_handler` (~200 tokens)

Run a module without deploying

Runs a handler or an endpoint on the platform using local files, without publishing them (tgcloud run). args is the payload (a Message for handlers/message, or the endpoint input) as a JSON5 object. ctx is the second argument (--ctx): the raw update for a handler, or initData for an endpoint, for example { initData: { user: { id: 1, first_name: "Ann" } } }. Returns the value, captured console logs, and elapsed time.

Input parameters:

- `args` (string): Handler payload or endpoint input as JSON5, for example '{ chat: { id: 1 }, text: "hi" }'
- `ctx` (string): Second-argument context as JSON5 (passed as --ctx)
- `module` (string, required): Module path, for example handlers/message or endpoints/getProfile
- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)

### `migrate` (~253 tokens)

Database migrations

Applies schema.js changes to the database (tgcloud migrate). push never does this. dry_run defaults to true (--dry-run): preview only. Applying (dry_run: false) requires confirm: true. apply "safe" passes --safe (auto-apply safe changes, skip warnings and manual steps). apply "yes" or omitting apply passes --yes (safe changes plus every warning, including .deprecated drops that delete data; manual type changes are still skipped). local: true diffs against the local schema.js instead of the deployed one (--local) and can be combined with either mode. Show the user the preview before applying. Warn when the preview contains a drop.

Input parameters:

- `apply` (string): When dry_run is false: "safe" → --safe, "yes" (default) → --yes
- `confirm` (boolean): Required confirm: true to apply migrations, including drops of .deprecated columns and tables
- `dry_run` (boolean): true (default) — preview only (--dry-run)
- `local` (boolean): Diff against local schema.js instead of the deployed schema (--local)
- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)

### `webhook_status` (~85 tokens)

Webhook status

Shows the platform-managed webhook (tgcloud webhook): URL, allowed_updates, pending update count, the last delivery error, and whether it is in sync with the deployed handlers. First step when a bot is silent. Deploying or removing a handler can leave it out of sync.

Input parameters:

- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)

### `webhook_sync` (~112 tokens)

Re-sync the webhook

Points the webhook at the platform and rebuilds allowed_updates from deployed handlers (tgcloud webhook sync). Call it after adding or removing a handler. drop_pending=true discards updates Telegram already queued — destructive, requires confirm: true.

Input parameters:

- `confirm` (boolean): Required confirm: true when drop_pending is true
- `drop_pending` (boolean): Discard queued updates (--drop-pending, requires confirm: true)
- `project_dir` (string, required): Absolute path to a tgcloud project directory (contains .tgcloud/)

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/sdamarketing-tgcloud-mcp/tgcloud-mcp#diagnostics

## Score history

- 2026-10-16: 83
- 2026-10-15: 82
- 2026-10-14: 83
- 2026-10-13: 50
- 2026-10-12: 50

## Common questions

### What is the tgcloud — Telegram serverless bots MCP server?

tgcloud — Telegram serverless bots is an MCP server listed in the public MCP registry as io.github.sdamarketing/tgcloud-mcp. MCP server for Telegram serverless bots: lifecycle, deploys, migrations, webhooks via tgcloud CLI. This page covers its npm package (tgcloud-mcp).

### Is the tgcloud — Telegram serverless bots MCP server safe to use?

tgcloud — Telegram serverless bots scores 83 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 16 October 2026. It declares no install or post-install scripts. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the tgcloud — Telegram serverless bots MCP server expose?

tgcloud — Telegram serverless bots exposes 16 tools: create_project, init_project, login_bot, add_module, upgrade, and 11 more. Their descriptions and schemas cost roughly 1,987 tokens of context every time the server is loaded.

### Is the tgcloud — Telegram serverless bots MCP server still maintained?

tgcloud — Telegram serverless bots is still listed as active in the MCP registry. We last reached this channel on 16 October 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the tgcloud — Telegram serverless bots MCP server under?

tgcloud — Telegram serverless bots declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

## Links

- npm package: https://www.npmjs.com/package/tgcloud-mcp
- Socket report: https://socket.dev/npm/package/tgcloud-mcp
- Repository: https://github.com/sdamarketing/tgcloud_mcp
- Changelog RSS feed: https://verifymcp.io/servers/sdamarketing-tgcloud-mcp/tgcloud-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/sdamarketing-tgcloud-mcp/tgcloud-mcp.json
- HTML version of this page: https://verifymcp.io/servers/sdamarketing-tgcloud-mcp/tgcloud-mcp