Telegram Notification MCP Server

Telegram 通知 MCP サーバー

📢 Discord がお好みですか？ Discord 通知には、Discord Notification MCP をご確認ください。

機能

• 🤖 MCP ツール：通知を送信するための send_telegram_message ツールを提供します
• 🚀 Cloudflare Workers：グローバルに分散されたサーバーレス環境で動作します
• 🔐 認証済み：Cloudflare シークレットに保存されたベアラートークンが必要です
• 🌐 ストリーム可能な HTTP：現在のステートレス MCP トランスポートを使用します
• 💬 メッセージの書式設定：Markdown と HTML の書式設定に対応しています
• 📝 書式設定：Markdown と HTML のメッセージ書式設定に対応しています

アーキテクチャ

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

• POST /mcp：MCP 通信用のステートレスなストリーム可能 HTTP エンドポイント
• GET /sse：410 Gone を返します。従来の SSE クライアントは /mcp に移行する必要があります
• TypeScript、MCP SDK、Cloudflare Agents SDK を使用して構築
• 適切な JSON-RPC 2.0 エラー処理
• Node.js 互換モードを有効化

セットアップ

前提条件

1. Telegram Bot： @BotFather 経由でボットを作成し、ボットトークンを取得します
2. Chat 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 の設定

ストリーム可能な 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 - lint の問題を修正します
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