Telegram Notification MCP Server

Telegram 通知 MCP 服务

📢 更喜欢 Discord？ 如需接收 Discord 通知，请查看 Discord Notification MCP。

功能

• 🤖 MCP 工具：提供用于发送通知的 send_telegram_message 工具
• 🚀 Cloudflare Workers：以无服务器方式运行，支持全球分发
• 🔐 身份验证：需要使用存储为 Cloudflare 密钥的 bearer token
• 🌐 可流式 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：向机器人发送消息，然后访问以下地址以获取 chat 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 中填写机器人令牌和 chat ID。此文件用于本地开发和部署。

2. 对于生产环境部署，生成 MCP bearer token 并设置 Cloudflare 密钥：

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

   注意：DEFAULT_CHAT_ID 是可选的。如果未设置，调用 send_telegram_message 工具时必须提供 chat_id 参数。

3. 如有需要，更新 wrangler.toml 中的 worker 名称

部署

部署到 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 和相同的 bearer token，将 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 chat 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

调试

测试身份验证

你可以验证端点是否会拒绝未携带其 bearer token 的请求：

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 通知：确认 BOT_TOKEN 和 DEFAULT_CHAT_ID 已在 Worker 环境中正确设置。

技术细节

• 语言：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