金大哥 - telegram-notification-mcp MCP 详情

article

README

🚀 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 兼容模式。

📦 安装指南

先决条件

Telegram 机器人：通过 @BotFather 创建一个机器人，并获取机器人令牌。
聊天 ID：向你的机器人发送一条消息，然后访问以下链接获取聊天 ID：
```
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
```
Cloudflare 账户：在 cloudflare.com 上注册账户。

安装步骤

克隆此仓库。
安装依赖：
```
pnpm install
```

配置

从示例文件创建 .dev.vars 文件：
```
cp .dev.vars.example .dev.vars
```
然后在 .dev.vars 文件中编辑你的机器人令牌和聊天 ID。此文件用于本地开发和部署。
对于生产部署，设置 Cloudflare 机密信息：
```
npx wrangler secret put BOT_TOKEN
npx wrangler secret put DEFAULT_CHAT_ID  # 可选
```
注意：DEFAULT_CHAT_ID 是可选的。如果未设置，则在调用 send_telegram_message 工具时必须提供 chat_id 参数。
如果需要，更新 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

此命令将执行以下操作：

pnpm format - 使用 Biome 格式化代码。
pnpm lint:fix - 修复代码检查问题。
pnpm cf-typegen - 生成 Cloudflare 类型。
pnpm type-check - 检查 TypeScript 类型。

测试服务器

# 测试 SSE 连接
curl http://localhost:8787/sse

# 测试健康端点
curl http://localhost:8787/

🐞 调试

测试 SSE 连接

你可以直接测试 SSE 端点：

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

这应该返回一个以 endpoint 事件开头的事件流。

常见问题

连接立即关闭：检查你的工作人员是否正在运行，并且可以通过指定的 URL 访问。
未收到 endpoint 事件：确保 SSE 头正确发送，并且流格式正确。
Telegram 通知未发送：验证你的 BOT_TOKEN 和 DEFAULT_CHAT_ID 是否在工作人员环境中正确设置。

🔧 技术细节

编程语言：TypeScript（ES2021 目标）
运行时环境：支持 Node.js 兼容模式的 Cloudflare Workers
协议：MCP（模型上下文协议）
传输协议：SSE 和可流式 HTTP
状态管理：持久对象（McpAgent 所需）
可观测性：启用监控功能

📚 参考资料

本项目参考了以下指南：

📂 相关项目

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

📄 许可证

本项目采用 MIT 许可证。

telegram-notification-mcp