By name: telebiz-mcp description: 通过使用 telebiz-tt 浏览器客户端，可以利用 MCP 访问 Telegram 数据。该客户端支持列出聊天记录、读取消息、进行搜索、管理文件夹以及通过已认证的 Telegram 会话发送消息。 metadata: {"clawdbot":{"emoji":"📱"}}
telebiz-mcp
这是一个用于通过 telebiz-tt 浏览器客户端与 Telegram 进行集成的工具（MCP，即 Message Center Protocol）。
快速使用指南（请先阅读此部分）
- 速率限制非常严格：每次请求最多允许 20 次调用，每分钟最多 30 次调用，每次调用之间至少需要 500 毫秒的延迟；执行复杂操作时延迟时间会增加至 1 秒。
- 在将多个聊天添加到文件夹时：请勿使用
batchAddToFolder并传入多个chatIds（已知存在问题），应依次调用addChatToFolder。 - 关于 CRM 链接：在我们的测试中，
linkEntityToChat的稳定性不佳。我们发现使用company时会出现验证错误，而使用organization时有时能成功，但后来也会失败。在上游明确说明数据结构或功能标志之前，请将linkEntityToChat视为不可靠的。 - 建议使用可逆的操作，并立即清理测试过程中产生的临时文件（如文件夹、群组等）。
架构
┌──────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Clawdbot │────▶│ MCP Server │────▶│ WebSocket Relay │
│ (mcporter) │ │ (stdio) │ │ (port 9716) │
└──────────────┘ └──────────────────┘ └────────┬────────┘
│
▼
┌─────────────────┐
│ Browser │
│ (telebiz-tt) │
│ [executor] │
└─────────────────┘
快速设置
先决条件
- 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. 验证连接
# Quick health check
cd ~/clawd/skills/telebiz-mcp
npm run health
# Should show:
# 📱 Telebiz MCP Status
# ────────────────────
# Relay: ✅ Running
# Executor: ✅ Connected
# Tools: 31 available
6. 通过 mcporter 进行测试
cd ~/clawd
mcporter call telebiz.listChats limit:5
健康状况监控
手动检查
# Check status
npm run health
# JSON output for automation
node dist/health.js --json
监控脚本
可以使用定时任务（cron）来监控系统的运行状态：
# Check and alert on changes
npm run monitor
# Quiet mode - only output on state change
node dist/monitor.js --quiet
# JSON output
node dist/monitor.js --json
错误代码说明：
0= 系统正常运行（中继正常，执行器已连接）1= 系统性能下降（中继正常，但执行器断开连接）2= 系统关闭（中继未运行）3= 系统状态发生变化（用于触发警报）
定时任务集成
将以下脚本添加到 crontab 中以实现定期监控：
# Check every 5 minutes, alert on changes
*/5 * * * * cd ~/clawd/skills/telebiz-mcp && node dist/monitor.js --quiet >> /var/log/telebiz-monitor.log 2>&1
心跳监控集成
请参考 HEARTBEAT.md 文件中的内容，了解如何使用 Clawdbot 进行监控：
### Telebiz MCP (every 2h)
- [ ] Run: `cd ~/clawd/skills/telebiz-mcp && npm run health`
- [ ] If degraded/down: Alert Albert via Telegram
可用工具
聊天工具
| 工具 | 功能描述 |
|---|---|
listChats |
根据类型、未读状态、是否已归档等条件列出聊天记录 |
getChatInfo |
获取聊天详情 |
getCurrentChat |
获取当前打开的聊天记录 |
openChat |
导航到指定聊天记录 |
archiveChat |
将聊天记录归档 |
unarchiveChat |
取消聊天记录的归档状态 |
pinChat |
将聊天记录固定到屏幕顶部 |
unpinChat |
取消聊天记录的固定状态 |
muteChat |
静音聊天通知 |
unmuteChat |
恢复聊天通知的静音状态 |
deleteChat |
删除聊天记录 ⚠️ |
消息工具
| 工具 | 功能描述 |
|---|---|
sendMessage |
发送文本消息（支持 Markdown 格式） |
forwardMessages |
在聊天记录之间转发消息 |
deleteMessages |
删除消息 ⚠️ |
searchMessages |
全局搜索或在指定聊天记录中搜索 |
getRecentMessages |
查看聊天记录的历史记录 |
markChatAsRead |
将所有消息标记为已读 |
文件夹工具
| 工具 | 功能描述 |
|---|---|
listFolders |
列出所有聊天文件夹 |
createFolder |
创建新文件夹 |
addChatToFolder |
将聊天记录添加到文件夹 |
removeChatFromFolder |
从文件夹中删除聊天记录 |
deleteFolder |
删除文件夹 ⚠️ |
成员工具
| 工具 | 功能描述 |
|---|---|
getChatMembers |
列出群组/频道的成员 |
addChatMembers |
将用户添加到群组 |
removeChatMember |
从群组中删除用户 |
createGroup |
创建新群组 |
用户工具
| 工具 | 功能描述 |
|---|---|
searchUsers |
按名称/用户名搜索用户 |
getUserInfo |
查看用户详情 |
批量工具
| 工具 | 功能描述 |
|---|---|
batchSendMessage |
向多个聊天记录发送消息 |
batchAddToFolder |
将多个聊天记录添加到文件夹 |
batchArchive |
将多个聊天记录归档 |
使用示例
查找需要回复的聊天记录
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
分页查看聊天记录历史
# Page 1 (newest 50)
mcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50 offset:0
# Page 2 (messages 51-100)
mcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50 offset:50
整理聊天记录
# List folders
mcporter call telebiz.listFolders
# Add chats to folder
mcporter call telebiz.batchAddToFolder chatIds='["-1001234","-1001235"]' folderId:5
速率限制
浏览器会实施速率限制，以防止 Telegram 的流量过载：
- 每次请求的最大调用次数：20 次
- 每分钟的最大调用次数：30 次
- 每次调用之间的最小延迟：500 毫秒
- 执行复杂操作（发送、转发、删除）时的延迟：1 秒
（这些限制值来自 Telebiz 的用户界面，是我们实际测试中观察到的有效限制。）
已知问题及解决方法（2026 年 2 月）
batchAddToFolder 在处理多个 chatIds 时失败
- 已知问题：
batchAddToFolder(folderId, chatIds=[one])可以正常工作，或返回“已包含”错误；而batchAddToFolder(folderId, chatIds=[two or more])会返回“错误：无法更新文件夹”。 - 解决方法：需要依次调用
addChatToFolder，例如：addChatToFolder(chatId=A, folderIds=[folderId])和addChatToFolder(chatId=B, folderIds=[folderId])。
linkEntityToChat 的稳定性问题/数据结构不匹配
- 问题现象（2026 年 2 月）：当
entityType为deal、contact或company时，linkEntityToChat会返回“验证错误”。 - 解决方法：
- 建议使用
createContact、createDeal或createCompany等接口来创建关联关系。 - 使用
associateEntities方法来连接deal和company/contact。
- 建议使用
- 在上游提供稳定的数据结构或错误信息之前，不要依赖
linkEntityToChat。
故障排除
中继未启动
# Check if port is in use
ss -tlnp | grep 9716
# Kill existing process
pkill -f "relay.js"
# Start fresh
./start-relay.sh
浏览器无法连接
- 检查
npm run health命令，确认中继是否正在运行。 - 查看浏览器控制台（F12）中的 WebSocket 错误信息。
- 确保在设置 → 代理 → 启用 MCP 中启用了 MCP 功能。
- 尝试刷新
telebiz-tt页面。
出现“执行器未连接”的错误
- 使用
telebiz-tt的浏览器标签页必须处于打开且可见状态（未暂停）。 - 确保已登录 Telegram 并且在中继设置中启用了 MCP 功能。
速率限制相关问题
- 减少批量操作的数量。
- 在执行操作之间增加延迟时间。
- 使用更精确的过滤条件以减少 API 调用次数。
会话过期
- 如果 Telegram 会话过期，请刷新
telebiz-tt页面。 - 如果系统提示，请重新登录。
- 在设置中重新启用 MCP 功能。
配置
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
TELEBIZ_PORT |
9716 |
中继 WebSocket 端口 |
TELEBIZ_RELAY_URL |
ws://localhost:9716 |
MCP 服务器的 WebSocket 连接地址 |
TELEBIZ_STATE_FILE |
~/.telebiz-mcp-state.json |
系统状态文件 |
mcporter 配置
配置文件位于 ~/clawd/config/mcporter.json：
{
"mcpServers": {
"telebiz": {
"url": "http://localhost:9718/mcp"
}
}
}
注意：请使用 HTTP URL（而非标准输入/输出接口），以避免冲突。
安全注意事项
- 浏览器会保存您的 Telegram 会话信息，请确保其安全性。
- 不要将中继端口（9716）暴露在互联网上。
- 在执行破坏性操作之前，请仔细检查工具的调用逻辑。
- 速率限制有助于防止意外发送大量消息（垃圾信息）。