Telegram Notification MCP Server

一个 MCP（模型上下文协议）服务器，当 Claude Code 完成任务时向 Telegram 发送通知。使用 TypeScript 和 Cloudflare Agents SDK 构建，可部署在 Cloudflare Workers 上。

📢 更喜欢 Discord？ 请查看 Discord Notification MCP 以获取 Discord 通知。

功能

• 🤖 MCP 工具：提供一个 send_telegram_message 工具用于发送通知

• 🚀 Cloudflare Workers：以无服务器方式运行，全球分布

• 🔐 认证：需要存储在 Cloudflare secret 中的 bearer token

• 🌐 流式 HTTP：使用当前无状态的 MCP 传输

• 💬 消息格式化：支持 Markdown 和 HTML 格式化

• 📝 格式化：支持 Markdown 和 HTML 消息格式化

Related MCP server: mcp-telegram-claudecode

架构

此服务器使用 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 机器人：通过 @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

   然后使用你的机器人令牌和聊天 ID 编辑 .dev.vars。此文件用于本地开发和部署。

2. 对于生产部署，生成 MCP bearer token 并设置 Cloudflare secrets：

   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 中的 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 仪表板设置持续部署。了解更多关于 git 与 cloudflare 集成 的信息

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 聊天 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 ... 头与 MCP_AUTH_TOKEN Cloudflare secret 匹配。

2. MCP 重连或超时：确认客户端使用 HTTP 传输和 /mcp 端点，而不是已弃用的 /sse 端点。

3. Telegram 通知未发送：验证你的 BOT_TOKEN 和 DEFAULT_CHAT_ID 在 Worker 环境中是否正确设置。

技术细节

• 语言：TypeScript（ES2021 目标）

• 运行时：Cloudflare Workers，支持 Node.js 兼容性

• 协议：MCP（模型上下文协议）

• 传输：无状态流式 HTTP

• 可观测性：已启用用于监控

参考

本项目基于以下指南构建：

• 构建远程 MCP 服务器 - Cloudflare Agents

• 模型上下文协议 (MCP) - Cloudflare Agents

• MCP 传输方法 - Cloudflare Agents

• Cloudflare MCP 模板 (remote-mcp-authless)

许可证

MIT