Telegram Notification MCP

🚀 Telegram Notification MCP Server

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

✨ 主な機能

• 🤖 MCPツール：通知を送信するためのsend_telegram_messageツールを提供します。
• 🚀 Cloudflare Workers：サーバーレスでグローバルに配信できます。
• 🔐 セキュア：Cloudflareのシークレットを使用して資格情報を管理します。
• 🌐 デュアルトランスポート：最大の互換性を得るために、SSEとStreamable HTTPの両方をサポートします。
• 💾 Durable Objects：McpAgentが必要とする状態管理を提供します。
• 💬 メッセージフォーマット：MarkdownとHTMLのフォーマットをサポートします。
• 📝 フォーマット：MarkdownとHTMLのメッセージフォーマットをサポートします。

📦 インストール

前提条件

1. Telegramボット：@BotFatherを通じてボットを作成し、ボットトークンを取得してください。
2. チャットID：ボットにメッセージを送信し、以下のURLを訪問してチャット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. 本番環境でのデプロイの場合は、Cloudflareのシークレットを設定します。

   npx wrangler secret put BOT_TOKEN
   npx wrangler secret put DEFAULT_CHAT_ID  # オプション
   

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

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

デプロイ

Cloudflare Workersにデプロイします。

Wranglerを使用してデプロイします。

# まずシークレットを設定
npx wrangler secret put BOT_TOKEN
npx wrangler secret put DEFAULT_CHAT_ID  # オプション

# その後デプロイ
pnpm run deploy

代替案：継続的デプロイ Cloudflareダッシュボードから直接継続的デプロイを設定することもできます。CloudflareとのGit統合について詳しく学ぶことができます。

Claude Codeの設定

CLIを使用してSSEトランスポート経由でClaude CodeにMCPサーバーを追加します。

# 本番環境のデプロイ (SSE)
claude mcp add telegram-notify https://your-worker-name.workers.dev/sse -t sse

# ローカル開発用
claude mcp add telegram-notify http://localhost:8787/sse -t sse

注意：このサーバーはSSE（Server-Sent Events）とStreamable HTTPトランスポートの両方をサポートしています。SSEは動作が良好ですが、Streamable HTTPはより高い信頼性を提供し、新しい標準です。

設定を確認するには、以下のコマンドを実行します。

claude mcp list

💻 使用例

利用可能なツール

send_telegram_message：Telegramに通知メッセージを送信します。

• text（必須）：送信するメッセージテキスト
• chat_id（オプション）：TelegramのチャットID（指定されていない場合はDEFAULT_CHAT_IDが使用されます）
• parse_mode（オプション）：メッセージのフォーマットとして"Markdown"または"HTML"
• disable_notification（オプション）：メッセージをサイレントモードで送信します。

使用例：

// 環境変数からDEFAULT_CHAT_IDを使用
await send_telegram_message({ text: "Task completed!" })

// 特定のチャットに送信（DEFAULT_CHAT_IDを上書き）
await send_telegram_message({ text: "Hello!", chat_id: "123456789" })

// Markdownフォーマットで送信
await send_telegram_message({ 
  text: "*Bold* and _italic_ text", 
  parse_mode: "Markdown" 
})

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

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

• 明示的に要求した場合：「完了したら通知して」または「Telegramで知らせて」
• 実行中にエラーが発生した場合
• 重要なマイルストーンに到達した場合
• ユーザーの入力または介入が必要な場合

例シナリオ

# あなたが言う："本番環境にデプロイし、完了したら通知して"
# 結果：🤖 Claude Code Notification
#         Deployment completed successfully! The app is now live.

# あなたが言う："すべてのテストを実行し、結果を知らせて"
# 結果：🤖 Claude Code Notification
#         All tests passed! 52/52 tests successful.

# あなたが言う："このデータを処理し、エラーがあれば通知して"
# 結果：🤖 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"

🔧 技術詳細

📚 ドキュメント

このプロジェクトは以下のガイドに沿って構築されました。

• Build a Remote MCP server - Cloudflare Agents
• Model Context Protocol (MCP) - Cloudflare Agents
• MCP Transport Methods - Cloudflare Agents
• Cloudflare MCP Template (remote-mcp-authless)

関連プロジェクト

• Discord Notification MCP - TelegramではなくDiscordに通知を送信します。

📄 ライセンス

MITライセンスの下で公開されています。