tgcloud — Telegram serverless bots

tgcloud-mcp — Telegram 无服务器机器人的 MCP 服务

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

非官方项目。这是社区工具（作者 @sdamarketing）， 与 Telegram 无关。该平台的官方工具是 @tgcloud/cli CLI。tgcloud-mcp 在 MCP 中封装了该 CLI。威胁模型： SECURITY.md。

让 AI 助手能够管理 Telegram 无服务器机器人 （core.telegram.org/bots/serverless）： 你说“创建机器人”“部署”“显示 webhook”——助手运行 tgcloud，你无需操作终端。

适用于任何 MCP 客户端：opencode、Claude Code、Claude Desktop、Cursor、VS Code (Copilot)、Windsurf、Zed。 同一 MCP 服务和技能也打包成一个 Agent Plugin （agent-plugin/），适用于 Codex、Cursor、Copilot、Kiro 和 VS Code。

文档

文档站点（docs7）和 Context7 索引： context7.com/sdamarketing/tgcloud_mcp。

部分	内容
入门	概览、快速入门、安装
使用	工具、资源、安全
帮助	故障排除、实用指南
参考	SETUP、晚间演练指南

其他语言：ru、zh、ar、de、fr。 命令：tgcloud-mcp setup、tgcloud-mcp update、tgcloud-mcp links、tgcloud-mcp --help。

功能

通过 tgcloud CLI 提供 16 个工具：

范围	工具	功能
生命周期	create_project、init_project、login_bot、add_module、upgrade	创建项目脚手架、使用 @BotFather 令牌关联机器人、新建处理程序、端点和 lib 模块，将 0.2.0 之前的布局迁移到 tgcloud/
同步	status、diff、push、deploy、pull、fetch、reset	查看更改、原子部署、为 Mini App 构建后推送、与云端同步
数据	run_handler、migrate	无需部署即可运行处理程序或端点；使用 --dry-run、--safe、--yes、--local 运行迁移
Webhook	webhook_status、webhook_sync	解决“机器人没有响应”的情况，重新指向 webhook

另提供 MCP 资源 tgcloud://docs/*——英文平台参考文档 （布局、导入规则、sdk/db、sdk/api、sdk/fetch、CLI、限制）。

工具描述和技能使用英文，以便模型遵循统一文本。 助手会被告知用你的语言回答。面向用户的文档有 英文、俄文、中文、阿拉伯文、德文和法文版本。

安全

• 破坏性调用需要确认。 reset、push --force、应用 upgrade、应用迁移，以及 webhook sync --drop-pending 都会拒绝在没有 confirm: true 的情况下运行。助手会展示更改并先征求确认。
• 令牌不会泄露。 机器人令牌通过 stdin 传给 CLI，并在每个工具结果中脱敏。

安装

建议使用 npm 包（通过 OIDC 可信发布和 Sigstore 来源证明发布）。curl | bash 虽然方便，但会运行远程脚本：请先阅读脚本（去掉 | bash），或使用 npm。

Node.js 20+（平台 CLI 需要 18+）。

npm：

npm install -g tgcloud-mcp
tgcloud-mcp setup

向导会写入 MCP 配置。选择同意安装 Agent Plugin 后，它会将 agent-plugin/ 复制到 ~/.tgcloud-mcp/agent-plugin、Cursor 的本地插件文件夹，以及 VS Code 的 chat.pluginLocations 中。

一条命令（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

从源码安装：

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

详情请见：docs/SETUP.md。

连接 Agent

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

变量	默认值	用途
TGCLOUD_CLI	npx	如何启动 CLI（也可以使用全局安装的 tgcloud）
TGCLOUD_CLI_ARGS	tgcloud	子命令前的参数
TGCLOUD_TIMEOUT_MS	120000	单条 CLI 命令的超时时间

示例

你： 在 ~/bots/echo 中创建一个回声机器人 Agent： create_project → login_bot（向 @BotFather 获取令牌）→ 编辑 handlers/message.js → push → webhook_sync。机器人已上线。 你： 测试一下 Agent： 使用 { chat: { id: 1 }, text: "hi" } 调用 run_handler，并显示输出和日志。

修改前端后，Agent 会调用 deploy（先构建，再推送）。普通的 push 会原样上传构建文件夹，不会运行打包器。

操作手册

一个晚上搭建带 Mini App 的无服务器机器人 — 详细教程为俄语；命令使用平台提供的命令。简短概述见 docs/cookbook.en.mdx，以及 ru、zh、ar、de、fr 版本。

技能

skills/tgcloud 是 Agent 遵循的操作流程：目录结构、导入、配方和防护规则。同一文件也位于 agent-plugin/skills/tgcloud/SKILL.md。 如果副本内容不一致，npm run docs:check 会报错。

npx skills add sdamarketing/tgcloud_mcp

仓库

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

许可证

MIT