Telegram Notification MCP

🚀 Telegram 通知 MCP 服務器

這是一個 MCP（模型上下文協議）服務器，當 Claude Code 完成任務時，它會向 Telegram 發送通知。該服務器使用 TypeScript 結合 Cloudflare Agents SDK 構建，可部署在 Cloudflare Workers 上。

✨ 主要特性

• 🤖 MCP 工具：提供 send_telegram_message 工具用於發送通知。
• 🚀 Cloudflare Workers：支持無服務器運行，具備全球分發能力。
• 🔐 安全可靠：使用 Cloudflare 機密信息存儲憑證。
• 🌐 雙傳輸協議：支持 SSE 和可流式 HTTP 兩種協議，確保最大兼容性。
• 💾 持久對象：支持 McpAgent 所需的狀態管理。
• 💬 消息格式：支持 Markdown 和 HTML 格式的消息。
• 📝 格式化：支持 Markdown 和 HTML 消息格式化。

🏗️ 架構

本服務器使用 Cloudflare 的 Agents SDK 實現了 MCP 規範：

• GET /sse：用於 MCP 通信的 SSE 端點。
• POST /mcp：用於 MCP 通信的可流式 HTTP 端點。
• 使用 TypeScript、MCP SDK 和 Cloudflare Agents SDK 構建。
• 具備完善的 JSON-RPC 2.0 錯誤處理機制。
• 使用持久對象處理有狀態連接（McpAgent 所需）。
• 啟用了 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. 對於生產部署，設置 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 傳輸將 MCP 服務器添加到 Claude Code：

# 用於生產部署（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（服務器發送事件）和可流式 HTTP 傳輸。雖然 SSE 運行良好，但可流式 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: "任務完成！" })

// 發送到特定聊天（覆蓋 DEFAULT_CHAT_ID）
await send_telegram_message({ text: "你好！", chat_id: "123456789" })

// 使用 Markdown 格式發送
await send_telegram_message({ 
  text: "*粗體* 和 _斜體_ 文本", 
  parse_mode: "Markdown" 
})

何時會收到通知

Claude Code 在以下情況下發送通知：

• 你明確要求："完成後通知我" 或 "在 Telegram 上告知我"。
• 執行過程中出現錯誤。
• 達到重要里程碑。
• 需要用戶輸入或干預。

示例場景

# 你說："部署到生產環境並在完成後通知我"
# 結果：🤖 Claude Code 通知
#         部署成功完成！應用現已上線。

# 你說："運行所有測試並告知我結果"
# 結果：🤖 Claude Code 通知
#         所有測試通過！52/52 個測試成功。

# 你說："處理此數據並在出現任何錯誤時通知我"
# 結果：🤖 Claude Code 通知
#         錯誤：處理第 451 行失敗 - 日期格式無效

CLAUDE.md 示例

為了鼓勵 Claude Code 有效使用 Telegram 通知，將以下內容添加到你的 CLAUDE.md 文件中：

# Telegram 通知

使用 mcp__telegram-notify__send_telegram_message 工具向 Telegram 發送通知。

- 以下情況始終發送 Telegram 通知：
  - 任務完全完成時。
  - 需要用戶輸入才能繼續時。
  - 出現需要用戶關注的錯誤時。
  - 用戶明確要求通知時（例如，"通知我"、"給我發送消息"、"告知我"）。

- 在通知中包含相關詳細信息：
  - 對於構建/測試：成功/失敗狀態和數量。
  - 對於錯誤：具體錯誤消息和文件位置。

- 使用簡潔、信息豐富的消息，例如：
  - "✅ 構建成功完成（2 分 34 秒）"
  - "❌ 測試失敗：3/52 個測試在 auth.test.ts 中失敗"
  - "⚠️ 需要權限修改 /etc/hosts"

🔧 開發

本地運行

# 啟動本地開發服務器
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 類型。

測試服務器

# 測試 SSE 連接
curl http://localhost:8787/sse

# 測試健康端點
curl http://localhost:8787/

🐞 調試

測試 SSE 連接

你可以直接測試 SSE 端點：

curl -N http://localhost:8787/sse

這應該返回一個以 endpoint 事件開頭的事件流。

常見問題

1. 連接立即關閉：檢查你的工作人員是否正在運行，並且可以通過指定的 URL 訪問。
2. 未收到 endpoint 事件：確保 SSE 頭正確發送，並且流格式正確。
3. Telegram 通知未發送：驗證你的 BOT_TOKEN 和 DEFAULT_CHAT_ID 是否在工作人員環境中正確設置。

🔧 技術細節

• 編程語言：TypeScript（ES2021 目標）
• 運行時環境：支持 Node.js 兼容模式的 Cloudflare Workers
• 協議：MCP（模型上下文協議）
• 傳輸協議：SSE 和可流式 HTTP
• 狀態管理：持久對象（McpAgent 所需）
• 可觀測性：啟用監控功能

📚 參考資料

本項目參考了以下指南：

• 構建遠程 MCP 服務器 - Cloudflare Agents
• 模型上下文協議（MCP） - Cloudflare Agents
• MCP 傳輸方法 - Cloudflare Agents
• Cloudflare MCP 模板（remote-mcp-authless）

📂 相關項目

• Discord 通知 MCP - 向 Discord 發送通知，而非 Telegram。

📄 許可證

本項目採用 MIT 許可證。