telegram-bot-mcp

一个 MCP 服务器，让 Claude 通过 Telegram Bot API 管理 Telegram 频道——按天追踪订阅者增长，并发布、编辑、置顶或删除帖子。

🇮🇷 راهنمای فارسی · 部署指南 · راهنمای دپلوی

这是什么

Telegram 的 Bot API 是一个普通的 HTTPS API。本仓库将其封装在 Model Context Protocol 中，让 AI 助手可以将其作为工具调用——比如问"这个频道这周表现如何？"而不是 curl https://api.telegram.org/bot.../getChatMemberCount。

它有两种形式，共享同一套工具定义：

如果你想要无需人工干预的每日报告，请选择远程服务器。如果你只使用 Claude Code，并且希望数据不离开你的机器，请选择插件。

工具

两个版本都暴露相同的八个工具。

快速开始（远程服务器）

1. 使用 @BotFather 创建一个机器人 → /newbot → 复制令牌。

2. 将机器人添加为频道的管理员。

3. 在 val.town 上创建一个 HTTP val，并粘贴 remote/telegram-mcp.ts。

4. 在 val 的侧边栏中设置三个环境变量：TELEGRAM_BOT_TOKEN、TELEGRAM_CHANNEL、MCP_PASSWORD。

5. 在 Claude 中：设置 → 连接器 → 添加自定义连接器 → https://<your-val>.web.val.run/mcp → 输入你的密码。

完整指南，包括本地插件路径和故障排除：docs/deployment.md。

安全

此仓库不会提交任何凭据。 config.json 和 .env 已被 gitignore 忽略；只有 .example 文件被跟踪。在推送任何 fork 之前，请使用 git status 确认这两个文件都不会出现。

远程服务器实现了完整的 OAuth 2.1 授权流程，而不是开放地暴露在互联网上：

• 根据 RFC 9728，没有有效 bearer 令牌的请求会收到 401，并在 WWW-Authenticate 头中指向资源元数据。

• 客户端动态注册（RFC 7591）；无需分发客户端密钥。

• 授权码受 PKCE (S256) 保护，重定向 URI 会与注册的集合进行验证。

• 访问令牌和刷新令牌使用 HMAC-SHA256 签名且无状态——访问令牌 24 小时，刷新令牌 30 天。

• 同意屏幕由你选择的 MCP_PASSWORD 保护。

你的机器人令牌保留在宿主的环境变量中，任何工具都不会返回它。

请像对待频道密码一样对待 MCP_PASSWORD。 任何拥有它的人都可以连接并发布帖子。

限制

Bot API 仅报告订阅者数量。帖子浏览量、转发量、覆盖人数以及 Telegram 官方的频道统计图表不会向机器人开放——这些需要一个使用管理该频道的用户账户登录的 MTProto 客户端。

机器人通常只能编辑自己发送的消息。Telegram 定义了一个 can_edit_messages 管理员权限（"可以编辑其他用户的消息；仅限频道"），但机器人对人工管理员发布的帖子的行为并没有明确的文档说明——在依赖它之前，请先在您自己的频道上测试。删除则不同：can_delete_messages 明确涵盖其他用户的消息。

增长对比需要历史存储在两次运行之间持续存在。在 Val Town 上，这是 blob 存储，并且会持久化。在本地插件中，它是一个 CSV 文件——请将其放在持久化的位置，而不是临时目录中。

仓库结构

remote/telegram-mcp.ts              Remote MCP server (Val Town HTTP val, Deno)
plugin/                             Claude Code plugin
  .claude-plugin/plugin.json          Plugin manifest
  .mcp.json                           stdio MCP server registration
  server/telegram_mcp_server.py        MCP server (Python 3, stdlib only)
  skills/telegram-channel-report/      Skill that turns tools into a readable report
  config.example.json                  Template — copy to config.json
tests/                              Test suite for the remote server
docs/                               Deployment guides (English / فارسی)

测试

npm test

需要 Node 22.6+。二十二项检查涵盖了 OAuth 流程（401 质询、发现文档、动态注册、PKCE 拒绝、令牌和刷新授权、伪造令牌拒绝）和 MCP 协议（初始化、通知、工具列表、增长增量计算、工具错误路径）。Telegram API 被模拟；无需网络访问，也无需真实的机器人令牌。

测试套件直接针对部署的源码运行——tests/build.mjs 只重写一行，即 Val Town blob 导入，其他内容不变。

许可证

MIT