tgcloud — Telegram serverless bots

tgcloud-mcp — Telegram サーバーレスボット用 MCP サーバー

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

非公式プロジェクトです。これはコミュニティ製のツール（作者 @sdamarketing）であり、 Telegram とは関係ありません。プラットフォームの公式ツールは @tgcloud/cli CLI です。tgcloud-mcp はこの CLI を MCP でラップします。脅威モデルについては、 SECURITY.md を参照してください。

AI アシスタントが Telegram のサーバーレスボット （core.telegram.org/bots/serverless）を管理できるようにします。 「ボットを作成して」「デプロイして」「Webhook を表示して」と伝えると、アシスタントが tgcloud を実行するため、ターミナルを操作する必要はありません。

あらゆる MCP クライアントで利用できます：opencode、Claude Code、Claude Desktop、Cursor、VS Code（Copilot）、Windsurf、Zed。 同じサーバーとスキルは、Codex、Cursor、Copilot、Kiro、VS Code 向けの 1 つの Agent Plugin（agent-plugin/）としても提供されています。

ドキュメント

ドキュメントサイト（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 をご覧ください。

エージェントを接続する

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

変数	デフォルト	用途
TGCLOUD_CLI	npx	CLI の起動方法（グローバルにインストールした tgcloud も使用できます）
TGCLOUD_CLI_ARGS	tgcloud	サブコマンドの前に指定する引数
TGCLOUD_TIMEOUT_MS	120000	1 つの CLI コマンドのタイムアウト

例

あなた： ~/bots/echo にエコーボットを作成して エージェント： create_project → login_bot（@BotFather にトークンを要求）→ handlers/message.js を編集 → push → webhook_sync。ボットが稼働します。 あなた： テストして エージェント： { chat: { id: 1 }, text: "hi" } を指定して run_handler を実行し、出力とログを表示します。

フロントエンドを編集した後、エージェントは deploy（ビルドしてからプッシュ）を呼び出します。通常の push は、ビルドフォルダーをそのままアップロードし、バンドラーは実行しません。

クックブック

一晩で作る、Mini App 付きサーバーレスボット — 詳しい手順はロシア語ですが、コマンドはプラットフォームのものです。簡単な概要は docs/cookbook.en.mdx と、ru、zh、ar、de、fr の各版をご覧ください。

スキル

skills/tgcloud は、エージェントが従う手順をまとめたものです。レイアウト、インポート、レシピ、ガードレールが含まれています。同じファイルが 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