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 许可证。