Telegram

telegram-mcp

由 Shreyas 构建 · 由 Globalion 发布

Telegram ⇆ Agent 双向桥接。不使用我们平台上的大模型。

你的 Agent（Claude Desktop、Cursor、自定义脚本）负责思考。我们 的平台负责传递消息：我们接收你在 Telegram 上发送的消息并将其存储， 等你的 Agent 轮询时再转交给它。当你的 Agent 有内容要回复时， 会通过我们推送到你的 Telegram。

• 自带 Agent。 任何 MCP 客户端都能使用。
• 中间不做推理。 我们不会调用大模型，也不存在供应商锁定。
• 双向通信。 get_new_messages 拉取传入消息，send_telegram_message 推送传出消息。
• 平台斜杠命令。 即使你的 Agent 离线，/help、/clear、/recent、/window、/usage 也都能使用。

托管版本位于 telegram.regiq.in，也可以使用下方的 Docker Compose 进行自托管。

使用（托管版）

1. 访问 https://telegram.regiq.in，使用 Google 登录。

2. 私信 @BotFather → /newbot。将令牌粘贴到控制面板。

3. 在控制面板中：Generate MCP API key，并复制密钥。

4. 将其添加到 Claude Desktop 的 claude_desktop_config.json（或 Cursor／任何 MCP 客户端）：

   {
     "mcpServers": {
       "telegram": {
         "url": "https://telegram.regiq.in/api/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_KEY_HERE"
         }
       }
     }
   }
   

5. 在 Telegram 上向你的机器人发送 /start。

现在，你的 Agent 可以调用 get_new_messages 查看你发送给它的内容，并调用 send_telegram_message 回复。

工具

工具	方向	说明
get_new_messages()	用户 → Agent	返回上次拉取后收到的消息。读取后即标记为已读。
send_telegram_message(text)	Agent → 用户	将文本发送到用户的 Telegram 机器人。
list_recent_messages(max=20)	读取	最近存储的 N 条消息，包含双向消息。不推进游标。
clear_history()	操作	清除该用户的存储历史记录。

斜杠命令（由平台处理）

由平台直接处理，不涉及你的 Agent。因此，即使没有客户端在轮询，/help 也能使用。

命令	效果
/start	将此 Telegram 聊天注册到你的账户。
/help	列出命令。
/recent [N]	显示最近存储的 N 条消息。
/clear	清除历史记录。
/window N	设置历史窗口（默认值为 20）。
/usage	存储的消息数量。

自托管

你需要：

• Docker + Compose
• Google OAuth 客户端 — Cloud Console。Scopes：openid、email、profile。重定向地址：<PUBLIC_BASE_URL>/api/auth/callback/google
• 用于 Telegram webhook 的公共 HTTPS 域名（Cloudflare Tunnel 或在本地运行 ngrok http 3012）

无需大模型密钥。 你的 Agent 使用自己的模型。

git clone https://github.com/globalion/telegram-mcp
cd telegram-mcp
cp .env.example .env
# fill NEXTAUTH_SECRET, GOOGLE_*, PUBLIC_BASE_URL
docker compose up -d
# open http://localhost:3012

架构

  Telegram app                                Your MCP agent
     ▲   │                                      ▲   │
     │   │ text                          poll   │   │ push
     │   ▼                                      │   ▼
   ┌──────────────────────────────────────────────────┐
   │  Our platform (Hetzner)                          │
   │  - /api/telegram/webhook/<per-user-secret>       │
   │    · slash-commands answered here                │
   │    · plain text stored, no reply                 │
   │  - /api/mcp   Bearer-auth JSON-RPC               │
   │    · get_new_messages, send_telegram_message     │
   │    · list_recent_messages, clear_history         │
   │  - Postgres: User, ApiKey, TelegramLink, Message │
   └──────────────────────────────────────────────────┘

每位用户的 webhook URL 路径段都是随机密钥，因此即使机器人令牌泄露，也无法将其指向其他人的账户。Google 登录仅用于身份验证和封禁依据——每条消息的身份由 MCP API 密钥和 chatId 确定。

许可证

MIT。参见 LICENSE。