Telegram MCP (Met44)

电报MCP网桥v2

  ](https://nodejs.org)

A. 模型上下文协议 （MCP）服务器，允许AI代理通过Telegram与您通信。支持 多台机器和代理 同时进行会话隔离。包括a Telegram迷你应用程序 用于通过手机管理会话。

无需配置 --安装程序处理一切，包括Telegram机器人的创建。

v2.1的新增功能

• 会话隔离 --每个MCP服务器实例都有一个唯一的 session_id 以及自己的Telegram主题+队列文件。同一软件中的多个代理（例如Windsurf）不再共享消息。
• session_id 在回应中 --每一个 interact() 响应包括 session_id 所以代理总是知道他们属于哪个会话。
• 基于主题的路由 --传入的Telegram消息会根据其论坛主题路由到正确的会话队列，防止跨会话泄漏。

v2中的新功能

• 单 interact 工具 --替换了4个单独的工具（发送/轮询/检查/等待）。一个电话就可以解决所有问题。
• 多机支持 --在多台机器上运行代理，每台机器都有自己的会话。消息将广播到所有活动会话。
• Telegram迷你应用程序 --管理会话、查看聊天历史记录以及从Telegram内的web UI发送消息。
• 自动CI/CD --GitHub Actions在3个操作系统×3个节点版本上运行测试，然后将webapp部署到GitHub Pages。

快速安装

下载 telegram-mcp-install.js 并运行：

node telegram-mcp-install.js

安装程序将：

1. 检查先决条件（Node.js 18+，npm）
2. 询问您使用哪个代理/IDE
3. 引导您完成Telegram机器人创建（打开BotFather）
4. 自动检测您的聊天ID
5. 安装MCP服务器+依赖项
6. 将配置注入代理的MCP配置（带备份）
7. 发送测试消息以确认其工作正常

支持的代理

运作原理

                                    Forum Group (Topics)
                                    ┌──────────────────────────┐
┌─────────────┐   Telegram API      │  📋 General (broadcast)   │
│  You (phone) │ ◄────────────────► │  💬 Topic: PC-A/cascade   │ ◄──► MCP Server A ◄──► Agent A
│              │                    │  💬 Topic: Laptop/agent   │ ◄──► MCP Server B ◄──► Agent B
│  Mini App    │                    │  💬 Topic: Server/worker  │ ◄──► MCP Server C ◄──► Agent C
└─────────────┘                    └──────────────────────────┘

每个代理会话都有自己的 Telegram论坛主题:

• 在主题中回复 → 只有那个代理会收到你的消息
• 一般职位 → 向所有活动代理广播
• 全隔离 --会话之间没有消息混合
• 本地电报用户界面 --主题是内置的Telegram功能

这 interact 工具

一个工具取代了旧的发送/轮询/检查/等待模式：

interact({ session_id, message?, wait? })
→ { ok, now, session_id, messages: [{text, ts}] }

为什么是一个工具？

• 没有被遗忘的民意调查 --每个呼叫都会检查消息，即使在发送时也是如此
• 没有过时的消息 --每次轮询时都会清除消息，不会累积
• 最小上下文 --空支票的费用约为15个代币；没有单独检查→投票舞
• 阻塞等待 — wait=120 在服务器端保持调用，没有快速轮询循环

代理流示例

1. interact({message: "Starting task: refactor auth module"})
   → {ok:true, sent:true, messages:[], pending:0, now:1700000000}

2. ... agent works for a while ...

3. interact({session_id: "abc"})                       // routine check
   → {ok:true, messages:[], now:1700000060, session_id:"abc"}

4. interact({session_id: "abc", message: "Done! Summary: ...", wait: 120})
   → {ok:true, messages:[{text:"looks good!", ts:1700000100}], now:1700000120, session_id:"abc"}

多机支持

每个MCP服务器实例都注册为 会话 自动创建自己的 论坛主题 在小组中。主题以机器/代理标签命名（例如。 🤖 WorkPC/cascade).

通过env变量配置每个实例的标识：

"env": {
  "TELEGRAM_BOT_TOKEN": "...",
  "TELEGRAM_CHAT_ID": "...",
  "TELEGRAM_MACHINE_LABEL": "WorkPC",
  "TELEGRAM_AGENT_LABEL": "cascade"
}

• 在主题中回复 → 只有该会话的代理接收消息
• 一般职位 → 向所有活动会话广播
• 主题在重新启动时重复使用（相同的机器/代理标签=相同的主题）

电报命令（一般主题）

• /start --显示网桥信息和活动会话
• /sessions --列出所有会话及其状态

设置要求

机器人需要处于 启用主题的超级组 并有 管理员权限 至少：

• 管理主题 --为新会话创建主题
• 安装程序将逐步指导您完成此设置

Telegram迷你应用程序

部署到GitHub Pages的轻量级仪表板，可作为Telegram迷你应用程序访问。

特征：

• 查看组连接状态
• 向特定会话主题发送消息或向General广播
• Telegram内部的快速访问控制面板
• 本地Telegram迷你应用程序集成（主题颜色、安全区域）

每会话对话在Telegram Topics中本地发生——迷你应用程序是一个方便快捷的覆盖层。

通过设置访问它 Telegram迷你应用程序 通过BotFather，指向您的GitHub Pages URL。

配置

安装后，使用configure命令切换行为标志：

node telegram-mcp-install.js configure

环境变量

行为标志

全部默认为 上。设置为 "false" 禁用。

传统兼容性

旧的4-tool界面(send_message, poll_messages, check_status, wait_for_reply)仍然通过内置的遗留处理程序工作。现有代理将继续运行，不做任何更改。

发展

telegram-mcp-bridge/
├── server.js          # MCP server (standalone, unified interact tool)
├── install.js         # Installer + configure command
├── build.js           # Builds single-file distributable
├── verify.js          # Verifies embedded base64 matches source
├── webapp/            # Telegram Mini App (static SPA)
│   ├── index.html
│   ├── style.css
│   └── app.js
├── test/              # Automated tests
│   ├── server.test.js
│   ├── build.test.js
│   └── config.test.js
├── .github/workflows/
│   └── ci.yml         # CI + GitHub Pages deploy
└── dist/
    ├── telegram-mcp-install.js
    └── server.js.sha256

npm install            # Install dev dependencies
npm test               # Run all tests (46 tests)
npm run build          # Rebuild distributable
npm run verify         # Verify embedded code matches source

快速部署

运行交互式安装程序：

# Windows
deploy.bat

# macOS/Linux  
./deploy.sh

安装程序将引导您完成以下操作：

• 机器人令牌创建（或现有令牌）
• 聊天ID检测
• 代理配置

CI/CD

关于推送 main:

1. 测试 在Ubuntu/Windows/macOS×节点18/20/22上运行
2. 语法检查 验证所有JS文件
3. Webapp部署 自动转到GitHub页面

卸载

• 视窗: %USERPROFILE%\.telegram-mcp-bridge\uninstall.bat
• macOS/Linux: ~/.telegram-mcp-bridge/uninstall.sh
• 然后删除 "telegram-bridge" 从您代理的MCP配置

贡献

欢迎投稿！拜托：

1. 分叉回购
2. 创建要素分支
3. 跑 npm test 验证
4. 提交PR

许可证

麻省理工学院