Telegram 通知 MCP サーバー

Claude Code がタスクを完了したときに Telegram へ通知を送信する MCP（Model Context Protocol）サーバー。Cloudflare Agents SDK を使用して TypeScript で構築され、Cloudflare Workers にデプロイ可能です。

📢 Discord をお使いですか？ Discord 通知は Discord 通知 MCP をご覧ください。

特徴

• 🤖 MCP ツール: 通知を送信するための send_telegram_message ツールを提供

• 🚀 Cloudflare Workers: サーバーレスでグローバルに配信

• 🔐 認証付き: Cloudflare シークレットとして保存されたベアラートークンが必要

• 🌐 Streamable HTTP: 現在のステートレス MCP トランスポートを使用

• 💬 メッセージ形式: Markdown および HTML 形式に対応

• 📝 形式: Markdown および HTML メッセージ形式に対応

Related MCP server: mcp-telegram-claudecode

アーキテクチャ

このサーバーは Cloudflare Agents SDK を使用して MCP 仕様を実装しています:

• POST /mcp: MCP 通信用のステートレス Streamable HTTP エンドポイント

• GET /sse: 410 Gone を返却。レガシー SSE クライアントは /mcp へ移行してください

• TypeScript、MCP SDK、Cloudflare Agents SDK で構築

• 適切な JSON-RPC 2.0 エラーハンドリング

• Node.js 互換モードを有効化

セットアップ

前提条件

1. Telegram ボット: @BotFather でボットを作成し、ボットトークンを取得します

2. チャット ID: ボットにメッセージを送信し、以下にアクセスしてチャット ID を取得します:

   https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

3. Cloudflare アカウント: cloudflare.com でサインアップします

インストール

1. このリポジトリをクローンします

2. 依存関係をインストールします:

   pnpm install

設定

1. サンプルファイルから .dev.vars を作成します:

   cp .dev.vars.example .dev.vars

   次に、.dev.vars にボットトークンとチャット ID を記入します。このファイルはローカル開発と本番デプロイの両方で使用されます。

2. 本番デプロイ用に、MCP ベアラートークンを生成し、Cloudflare シークレットを設定します:

   openssl rand -hex 32
   pnpm exec wrangler secret put BOT_TOKEN
   pnpm exec wrangler secret put DEFAULT_CHAT_ID  # Optional
   pnpm exec wrangler secret put MCP_AUTH_TOKEN

   注: DEFAULT_CHAT_ID はオプションです。設定しない場合は、send_telegram_message ツールを呼び出す際に chat_id パラメータを指定する必要があります。

3. 必要に応じて wrangler.toml のワーカー名を更新します

デプロイ

Cloudflare Workers にデプロイします:

Wrangler を使用してデプロイ:

# First set secrets
pnpm exec wrangler secret put BOT_TOKEN
pnpm exec wrangler secret put DEFAULT_CHAT_ID  # Optional

# Then deploy
pnpm run deploy

代替: 継続的デプロイ

Cloudflare ダッシュボードから直接継続的デプロイを設定することもできます。詳細は Cloudflare の Git 連携 をご覧ください。

Claude Code 設定

Streamable HTTP と同一のベアラートークンを使用して、MCP サーバーを Claude Code に追加します:

# For production deployment
claude mcp add --scope user --transport http \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  telegram-notify https://your-worker-name.workers.dev/mcp

# For local development
claude mcp add --transport http \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  telegram-notify http://localhost:8787/mcp

このトークンは MCP エンドポイントへのクライアントアクセス用であり、Telegram ボットトークンではありません。ボットトークンを Claude の MCP 設定に入れないでください。

以下のコマンドで設定を確認できます:

claude mcp list

使用方法

設定が完了すると、Claude Code は必要なときにいつでも Telegram へ通知を送信できます。

利用可能なツール

send_telegram_message: Telegram へ通知メッセージを送信します

• text（必須）: 送信するメッセージテキスト

• chat_id（オプション）: Telegram チャット ID（未指定の場合は DEFAULT_CHAT_ID を使用）

• parse_mode（オプション）: メッセージ形式の "Markdown" または "HTML"

• disable_notification（オプション）: サイレントでメッセージを送信

使用例:

// Uses DEFAULT_CHAT_ID from environment
await send_telegram_message({ text: "Task completed!" })

// Send to specific chat (overrides DEFAULT_CHAT_ID)
await send_telegram_message({ text: "Hello!", chat_id: "123456789" })

// Send with Markdown formatting
await send_telegram_message({ 
  text: "*Bold* and _italic_ text", 
  parse_mode: "Markdown" 
})

通知を受け取るタイミング

Claude Code は以下の場合に通知を送信します:

• 明示的に依頼した場合: 「完了したら通知して」や「Telegram で知らせて」

• 実行中にエラーが発生した場合

• 重要なマイルストーンに到達した場合

• ユーザーの入力や介入が必要な場合

シナリオ例

# You say: "Deploy to production and notify me when done"
# Result: 🤖 Claude Code Notification
#         Deployment completed successfully! The app is now live.

# You say: "Run all tests and let me know the results"
# Result: 🤖 Claude Code Notification
#         All tests passed! 52/52 tests successful.

# You say: "Process this data and notify me if there are any errors"
# Result: 🤖 Claude Code Notification
#         Error: Failed to process row 451 - invalid date format

通知例

CLAUDE.md への記載例

Claude Code が Telegram 通知を効果的に使用するよう促すには、CLAUDE.md に以下を追加します:

# Telegram Notifications

Use the mcp__telegram-notify__send_telegram_message tool to send notifications to Telegram.

- Always send a Telegram notification when:
  - A task is fully complete
  - You need user input to continue
  - An error occurs that requires user attention
  - The user explicitly asks for a notification (e.g., "notify me", "send me a message", "let me know")

- Include relevant details in notifications:
  - For builds/tests: success/failure status and counts
  - For errors: the specific error message and file location

- Use concise, informative messages like:
  - "✅ Build completed successfully (2m 34s)"
  - "❌ Tests failed: 3/52 failing in auth.test.ts"
  - "⚠️ Need permission to modify /etc/hosts"

開発

ローカルで実行:

# Start local development server
pnpm dev

ローカル開発では、Wrangler が .dev.vars ファイルから環境変数を自動的に読み込みます。

デプロイ前にすべてのチェックを実行:

pnpm build

このコマンドは以下を実行します:

1. pnpm format - Biome でコードをフォーマット

2. pnpm lint:fix - リンティングの問題を修正

3. pnpm cf-typegen - Cloudflare 型を生成

4. pnpm type-check - TypeScript の型をチェック

サーバーをテスト:

# An unauthenticated request must return HTTP 401
curl -i http://localhost:8787/mcp

# Claude Code performs the authenticated MCP handshake and health check
claude mcp list

デバッグ

認証のテスト

ベアラートークンなしでエンドポイントがリクエストを拒否することを確認できます:

curl -i http://localhost:8787/mcp

これにより 401 Unauthorized が返されるはずです。その後、claude mcp list を使用して、認証済みクライアント接続を確認します。

一般的な問題

1. 401 Unauthorized: クライアントの Authorization: Bearer ... ヘッダーが Cloudflare シークレットの MCP_AUTH_TOKEN と一致しているか確認してください。

2. MCP の再接続またはタイムアウト: クライアントが HTTP トランスポートと /mcp エンドポイントを使用しているか確認してください。廃止された /sse エンドポイントではありません。

3. Telegram 通知が送信されない: Worker 環境で BOT_TOKEN と DEFAULT_CHAT_ID が正しく設定されているか確認してください。

技術詳細

• 言語: TypeScript（ES2021 ターゲット）

• ランタイム: Node.js 互換モードの Cloudflare Workers

• プロトコル: MCP（Model Context Protocol）

• トランスポート: ステートレス Streamable HTTP

• 可観測性: モニタリング有効

参考資料

このプロジェクトは以下のガイドに基づいて構築されています:

• リモート MCP サーバーの構築 - Cloudflare Agents

• Model Context Protocol（MCP）- Cloudflare Agents

• MCP トランスポート方式 - Cloudflare Agents

• Cloudflare MCP テンプレート（remote-mcp-authless）

ライセンス

MIT