Telegram MCP 服务器：安全地为 AI 智能体提供完整的 Telegram Bot API

为什么 AI 智能体需要 Telegram 封装层

AI 智能体越来越擅长操作真实的工具。它们可以读取仪表盘、判断重点，并执行下一步。但要在 Telegram 中采取行动，它们需要一座桥梁：把「置顶 AMA 公告并开一个提问话题」这样的一句话，转换成正确的 Telegram API 调用。

这座桥梁就是 Telegram MCP 服务器。

Model Context Protocol（MCP）是一项开放标准，让 Claude、ChatGPT、Cursor 和 Codex 等 AI 客户端能够发现并调用工具。Telegram MCP 服务器将 Telegram 操作以工具的形式暴露出来，并附带模型可以遵循的清晰描述和输入结构。

现在，Metricgram 为您托管这样一个服务器，背后正是已经在管理您群组的那个机器人。

「封装 Telegram Bot API」到底意味着什么

纸面上看，为智能体封装 Bot API 似乎很简单。实际上，您需要：

• 托管一个机器人，保管好它的令牌并保持其持续运行。
• 通过 Webhook 或轮询接收更新。
• 为希望智能体使用的每个接口编写工具定义。
• 阻止智能体向不该触碰的聊天发送消息。
• 处理频率限制、迁移后的超级群组以及 Telegram 错误信息。
• 让重试变得安全，避免一次不稳定的网络请求导致同一条消息被发两次。
• 记录智能体做过的事情，以便日后需要时说明原因。

大多数团队做到「发送消息」就止步了，因为剩下的都是大量繁琐的底层工作。结果就是一个会说话、却无法真正管理社区的智能体。

Metricgram Telegram MCP 服务器如何运作

Metricgram 已经以管理员机器人（或您自己的自定义机器人）的身份存在于您的 Telegram 群组中。MCP 服务器只是让您的 AI 客户端通过一个托管端点使用这个机器人：

1. 连接您的群组 到 Metricgram，并授予机器人管理员权限。
2. 将端点 https://metricgram.com/api/v1/mcp 添加到您的 AI 客户端，例如在 Claude 中添加为自定义连接器。
3. 登录并通过 OAuth 批准访问。就这么简单：无需管理服务器、Webhook 或令牌。不支持 OAuth 的客户端可以改用 API 密钥，配置如下。

{
  "mcpServers": {
    "metricgram": {
      "url": "https://metricgram.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Claude Desktop 用户可以通过 mcp-remote 桥接同一个端点。各客户端的具体配置片段都在管理面板的 MCP 页面中。

70 多个 Bot API 方法，两种调用方式

服务器分两层提供 Telegram Bot API。

用于日常工作的类型化工具

常见任务都有专门的工具和描述清晰的参数，让模型更容易正确使用：

• send_telegram_message，支持话题、回复和 URL 按钮
• send_telegram_media，用于图片、视频、GIF、文档、音频和贴纸
• send_telegram_poll，用于投票和测验
• edit_telegram_message、delete_telegram_messages、react_to_telegram_message
• pin_telegram_message 和 forward_telegram_message
• manage_forum_topic，用于创建、重命名、关闭、重新打开或删除话题
• get_telegram_chat 和 get_telegram_chat_member，获取实时聊天数据
• handle_telegram_join_request、create_telegram_invite_link 和 update_telegram_chat_settings

完整的 Bot API 网关

其他所有操作都通过 telegram_bot_api 完成。智能体传入官方 Bot API 方法名及其参数，例如 setChatPermissions、banChatSenderChat、editMessageMedia、hideGeneralForumTopic 或 revokeChatInviteLink。配套工具 telegram_api_methods 会列出当前密钥可以使用的所有方法，因此智能体始终清楚有哪些能力可用。

安全性：为什么智能体从不自行选择 chat_id

最重要的设计决策，是智能体 不能 做什么。

• 聊天被锁定。 智能体传入的是 Metricgram 的 group_id。服务器根据您拥有的群组推导出 Telegram chat_id，并拒绝任何其他聊天。
• 转发和引用会被检查。 消息只能从您自己的群组中转发、复制或引用。
• 排除影响整个机器人的操作。 Webhook、支付、机器人资料修改和退出群组均不对外开放。
• 按钮是安全的。 内联按钮可以打开 URL 或复制文本，但无法向机器人触发回调。
• 权限范围与信任匹配。 telegram:read、telegram:write、telegram:moderate 和 telegram:admin 彼此独立，您可以保留多个权限不同的密钥。
• 重试具备幂等性。 写入类工具支持 idempotency_key，重试的调用会返回第一次的结果，而不会重复执行。
• 每次调用都会记录 所用的工具和 Bot API 方法。

智能体通过官方 Bot API 以机器人身份操作，绝不会使用您的个人 Telegram 账号。

普通机器人没有的上下文

一个单纯的 Bot API 封装可以执行操作，但看不到太多信息。Metricgram MCP 服务器还提供社区洞察：

• 分析概览和活跃度时间序列
• 活跃成员、成员历史和已采集的消息
• 游戏化排行榜和奖励
• 群组动态的 AI 摘要
• Stripe 订阅者健康度和存在流失风险的续费

这意味着智能体可以先回答「这个月谁不再参与了？」，然后给他们发送一条用心的消息，全部在一次对话中完成。

工作流示例

每周公告。「在 Crypto Talk 发布每周 AMA 公告，置顶但不通知所有人，开一个 AMA 提问话题，并创建一个周五过期的邀请链接。」

内容清理。「检查最近 200 条消息中的垃圾链接，删除它们，并将发送者限制 24 小时。」

社区报告。「对比本周和上周的活跃度，列出最活跃的五位成员，并在 General 话题中发一条简短的感谢消息。」

入群申请筛选。「批准来自有效订阅者的待处理入群申请，拒绝其余申请。」

适合哪些人

• 社区主理人：希望有一个助手处理日常管理工作。
• 代理机构：管理众多客户群组，希望用一个智能体统一处理。
• 支持和客户成功团队：在 Telegram 上运营客户社区。
• 开发者：希望在智能体技术栈中接入 Telegram，而无需运行机器人基础设施。

开始使用

MCP 服务器包含在所有 Metricgram 套餐和 14 天免费试用中，您可以在付费前先接入智能体。大多数客户端通过 OAuth 连接：粘贴服务器 URL，登录并批准访问即可。不支持 OAuth 的客户端仍可使用 API 密钥。

在 Telegram MCP 服务器页面 和 MCP 功能概览 了解更多，然后在管理面板中创建您的第一个密钥。