名称： telebiz-mcp
描述： 通过 telebiz-tt 浏览器客户端，使用 MCP 访问 Telegram 数据。可列出聊天、读取消息、搜索、管理文件夹，并通过已认证的 Telegram 会话发送消息。
元数据： {"clawdbot":{"emoji":"📱"}}

telebiz-mcp

通过 telebiz-tt 浏览器客户端实现的 Telegram MCP 集成。

快速规则（请先阅读）

• 速率限制严格：单次请求最多 20 次调用，每分钟最多 30 次调用，调用间隔至少 500ms，重度操作（发送/转发/删除）间隔至少 1s。
• 添加多个聊天到文件夹时：请勿使用带多个 chatIds 的 batchAddToFolder（已知 Bug）。请顺序循环调用 addChatToFolder。
• 关于 CRM 关联：在我们的测试中，linkEntityToChat 不稳定。我们观察到 company 类型会因验证错误而失败，而 organization 类型曾成功过一次，但后来也失败了。在上游明确其模式/功能标志前，请将 linkEntityToChat 视为不可靠。
• 优先使用可逆操作，并立即清理测试产物（文件夹、群组）。

架构

┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│ Clawdbot     │────▶│ MCP 服务器       │────▶│ WebSocket 中继  │
│ (mcporter)   │     │ (stdio)          │     │ (端口 9716)     │
└──────────────┘     └──────────────────┘     └────────┬────────┘
                                                       │
                                                       ▼
                                              ┌─────────────────┐
                                              │ 浏览器          │
                                              │ (telebiz-tt)    │
                                              │ [执行器]        │
                                              └─────────────────┘

快速设置

先决条件

• Node.js 18+
• Telegram 账号

1. 安装 telebiz-mcp

npm install -g @telebiz/telebiz-mcp

2. 在浏览器中打开 Telebiz

访问 https://telebiz.io 并使用您的 Telegram 账号登录。

3. 启动 HTTP 服务器

cd ~/clawd/skills/telebiz-mcp
./start-http.sh

这将启动一个持久化服务器，其功能包括：
- 内部运行 telebiz-mcp
- 保持浏览器连接活跃
- 在端口 9718 上暴露 HTTP API

4. 在 Telebiz 中启用 MCP

在 telebiz.io 中：设置 → 代理 → 本地 MCP

服务器运行后，状态应显示为“已连接”。

5. 验证连接

# 快速健康检查
cd ~/clawd/skills/telebiz-mcp
npm run health

# 应显示：
# 📱 Telebiz MCP 状态
# ────────────────────
# 中继: ✅ 运行中
# 执行器: ✅ 已连接
# 可用工具: 31

6. 通过 mcporter 测试

cd ~/clawd
mcporter call telebiz.listChats limit:5

健康监控

手动检查

# 检查状态
npm run health

# 自动化用的 JSON 输出
node dist/health.js --json

监控脚本

监控脚本跟踪状态变化，可与 cron 配合使用：

# 检查并在状态变化时告警
npm run monitor

# 静默模式 - 仅在状态变化时输出
node dist/monitor.js --quiet

# JSON 输出
node dist/monitor.js --json

退出码：
- 0 = 健康（中继运行，执行器已连接）
- 1 = 降级（中继运行，执行器断开）
- 2 = 宕机（中继未运行）
- 3 = 状态已改变（用于告警）

Cron 集成

添加到 crontab 以进行定期监控：

# 每 5 分钟检查一次，状态变化时告警
*/5 * * * * cd ~/clawd/skills/telebiz-mcp && node dist/monitor.js --quiet >> /var/log/telebiz-monitor.log 2>&1

心跳集成

添加到 HEARTBEAT.md 以供 Clawdbot 监控：

### Telebiz MCP (每 2 小时)
- [ ] 运行: `cd ~/clawd/skills/telebiz-mcp && npm run health`
- [ ] 如果降级/宕机: 通过 Telegram 通知 Albert

可用工具

聊天工具

消息工具

文件夹工具

成员工具

用户工具

批量工具

使用示例

查找等待我回复的聊天

mcporter call telebiz.listChats iAmLastSender=false hasUnread=true limit:20

查找我发起但已停滞的对话

mcporter call telebiz.listChats iAmLastSender=true lastMessageOlderThanDays:7 limit:20

搜索所有消息

mcporter call telebiz.searchMessages query="invoice" limit:20

在指定聊天中搜索

mcporter call telebiz.searchMessages query="meeting" chatId=-1001234567890 limit:10

发送消息

mcporter call telebiz.sendMessage chatId=-1001234567890 text="Hello from Clawdbot!"

获取最近消息

mcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50

分页浏览历史记录

# 第 1 页（最新的 50 条）
mcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50 offset:0

# 第 2 页（第 51-100 条）
mcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50 offset:50

整理聊天

# 列出文件夹
mcporter call telebiz.listFolders

# 将聊天添加到文件夹
mcporter call telebiz.batchAddToFolder chatIds='["-1001234","-1001235"]' folderId:5

速率限制

浏览器强制执行速率限制，以防止触发 Telegram 的洪水保护机制：
- 单次请求最大调用次数：20
- 每分钟最大调用次数：30
- 调用间最小延迟：500ms
- 重度操作延迟（发送/转发/删除）：1s

（这些值来自 Telebiz UI，是我们实际观察到的有效限制。）

已知问题 / 解决方法 (2026年2月)

batchAddToFolder 对多个 chatIds 失败

观察到的行为：
- batchAddToFolder(folderId, chatIds=[单个]) 有效（或报告 alreadyIncluded）
- batchAddToFolder(folderId, chatIds=[两个或更多]) 失败，错误信息："Error: Failed to update folder"
- 已确认在以下两种情况均可复现：
- 汽车群组 + 另一个群组
- 汽车群组 + 一个私聊

解决方法： 顺序循环调用：
- addChatToFolder(chatId=A, folderIds=[folderId])
- addChatToFolder(chatId=B, folderIds=[folderId])

linkEntityToChat 不稳定 / 模式不匹配

观察到的行为 (2026年2月)：
- linkEntityToChat 对 entityType=deal、contact 和 company 返回 "Validation error"。
- 在一次运行中，使用 entityType="organization" 成功将 HubSpot 公司关联到聊天，但后来 organization 也返回了 "Validation error"。

影响： 此工具可能受功能标志控制、服务器端验证规则变化，或者发布的模式/枚举与后端期望不匹配。

解决方法：
- 优先通过 createContact/createDeal/createCompany 进行关联（这些工具在创建时即关联到聊天）。
- 使用 associateEntities 来连接 deal↔company/contact。
- 在上游提供稳定的契约和更好的错误信息之前，不要依赖 linkEntityToChat。

故障排除

中继无法启动

# 检查端口是否被占用
ss -tlnp | grep 9716

# 终止现有进程
pkill -f "relay.js"

# 重新启动
./start-relay.sh

浏览器无法连接

1. 验证中继是否运行：npm run health
2. 检查浏览器控制台 (F12) 的 WebSocket 错误
3. 确保在 设置 → 代理 → 启用 MCP 中已启用 MCP
4. 尝试刷新 telebiz-tt 页面

"执行器未连接" 错误

包含 telebiz-tt 的浏览器标签页必须：
- 处于打开且可见状态（未被挂起）
- 已登录 Telegram
- 在设置中启用了 MCP

速率限制错误

• 减小批量操作的大小
• 在操作间增加延迟
• 使用更具体的过滤器以减少 API 调用次数

会话过期

如果 Telegram 会话过期：
1. 刷新 telebiz-tt 浏览器页面
2. 如有提示，重新登录
3. 在设置中重新启用 MCP

配置

环境变量

mcporter 配置

位于 ~/clawd/config/mcporter.json：

{
  "mcpServers": {
    "telebiz": {
      "url": "http://localhost:9718/mcp"
    }
  }
}

注意：使用 HTTP URL（而非 stdio）以避免产生冲突。

安全须知

• 浏览器持有您的 Telegram 会话 - 请确保其安全
• 请勿将中继端口 (9716) 暴露到互联网
• 在执行破坏性操作前，请仔细审查工具调用
• 速率限制有助于防止意外发送垃圾信息