Telegram

telegram-mcp

Shreyas が開発 · Globalion が提供

双方向の Telegram ⇆ エージェントブリッジ。スタック内に LLM はありません。

エージェント（Claude Desktop、Cursor、カスタムスクリプト）が頭脳です。プラットフォームはパイプの役割を果たします。Telegram で送信したメッセージを受け取り、保存して、エージェントがポーリングしたときに渡します。エージェントが返信する内容を用意すると、プラットフォーム経由で Telegram に送信します。

• エージェントは自由に選べます。 どの MCP クライアントでも動作します。
• 途中で推論は行いません。 LLM は呼び出しません。ベンダーロックインもありません。
• 双方向です。 get_new_messages で受信し、send_telegram_message で送信します。
• プラットフォームのスラッシュコマンド。 エージェントがオフラインでも、/help、/clear、/recent、/window、/usage はすべて動作します。

telegram.regiq.in でホストされています。以下の Docker Compose を使ってセルフホストすることもできます。

使用方法（ホスト版）

1. https://telegram.regiq.in にアクセスし、Google でサインインします。

2. @BotFather に DM を送り、/newbot を実行します。トークンをダッシュボードに貼り付けます。

3. ダッシュボードで Generate MCP API key を選択し、キーをコピーします。

4. Claude Desktop の claude_desktop_config.json（または Cursor／任意の MCP クライアント）に追加します。

   {
     "mcpServers": {
       "telegram": {
         "url": "https://telegram.regiq.in/api/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_KEY_HERE"
         }
       }
     }
   }
   

5. Telegram でボットに /start を送信します。

これでエージェントは get_new_messages を呼び出して送信した内容を確認し、send_telegram_message を呼び出して返信できるようになります。

ツール

ツール	方向	備考
get_new_messages()	ユーザー → エージェント	前回の取得以降に受信したメッセージを返します。一度だけ読み取れます。
send_telegram_message(text)	エージェント → ユーザー	ユーザーの Telegram ボットにテキストを送信します。
list_recent_messages(max=20)	読み取り	双方向の直近 N 件の保存済みメッセージです。カーソルは進みません。
clear_history()	操作	ユーザーの保存済み履歴を消去します。

スラッシュコマンド（プラットフォームが処理）

プラットフォームが直接処理するため、エージェントは関与しません。そのため、ポーリングが行われていなくても /help は動作します。

コマンド	効果
/start	この Telegram チャットをアカウントに登録します。
/help	コマンド一覧を表示します。
/recent [N]	直近の保存済みメッセージ N 件を表示します。
/clear	履歴を消去します。
/window N	履歴ウィンドウを設定します（既定値は 20）。
/usage	保存済みメッセージ数を表示します。

セルフホスト

必要なもの：

• Docker + Compose
• Google OAuth クライアント — Cloud Console。スコープ：openid、email、profile。リダイレクト先：<PUBLIC_BASE_URL>/api/auth/callback/google
• Telegram Webhook 用のパブリックな HTTPS ドメイン（Cloudflare Tunnel、またはローカルで ngrok http 3012）

LLM キーは不要です。 エージェントが独自のモデルを使用します。

git clone https://github.com/globalion/telegram-mcp
cd telegram-mcp
cp .env.example .env
# fill NEXTAUTH_SECRET, GOOGLE_*, PUBLIC_BASE_URL
docker compose up -d
# open http://localhost:3012

アーキテクチャ

  Telegram app                                Your MCP agent
     ▲   │                                      ▲   │
     │   │ text                          poll   │   │ push
     │   ▼                                      │   ▼
   ┌──────────────────────────────────────────────────┐
   │  Our platform (Hetzner)                          │
   │  - /api/telegram/webhook/<per-user-secret>       │
   │    · slash-commands answered here                │
   │    · plain text stored, no reply                 │
   │  - /api/mcp   Bearer-auth JSON-RPC               │
   │    · get_new_messages, send_telegram_message     │
   │    · list_recent_messages, clear_history         │
   │  - Postgres: User, ApiKey, TelegramLink, Message │
   └──────────────────────────────────────────────────┘

ユーザーごとの Webhook URL セグメントにはランダムなシークレットを使用するため、ボットトークンが漏えいしても、他のユーザーのアカウントを指すように設定することはできません。Google サインインは本人確認とアカウント停止時の識別子としてのみ使用されます。メッセージごとの本人確認には MCP API キーと chatId を使用します。

ライセンス

MIT。LICENSE を参照してください。