--- name: telebiz-mcp description: Access Telegram data via MCP using the telebiz-tt browser client. Lists chats, reads messages, searches, manages folders, and sends messages through an authenticated Telegram session. metadata: {"clawdbot":{"emoji":"📱"}} ---

telebiz-mcp

MCP integration for Telegram via telebiz-tt browser client.

Quick Rules (read this first)

• Rate limits are strict: max 20 calls/request, 30 calls/min, 500ms between calls, heavy ops 1s.
• For adding many chats to folders: do NOT use batchAddToFolder with multiple chatIds (known bug). Loop addChatToFolder sequentially.
• For CRM linking: linkEntityToChat is unstable in our tests. We observed company failing with Validation error, and at one point organization succeeding — but later organization also failed. Treat linkEntityToChat as unreliable until upstream clarifies schema/feature flags.
• Prefer reversible operations and clean up test artifacts (folders, groups) immediately.

Architecture

┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│ Clawdbot     │────▶│ MCP Server       │────▶│ WebSocket Relay │
│ (mcporter)   │     │ (stdio)          │     │ (port 9716)     │
└──────────────┘     └──────────────────┘     └────────┬────────┘
                                                       │
                                                       ▼
                                              ┌─────────────────┐
                                              │ Browser         │
                                              │ (telebiz-tt)    │
                                              │ [executor]      │
                                              └─────────────────┘

Quick Setup

Prerequisites

• Node.js 18+
• Telegram account

1. Install telebiz-mcp

npm install -g @telebiz/telebiz-mcp

2. Open Telebiz in browser

Go to https://telebiz.io and login with your Telegram account.

3. Start the HTTP server

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

This starts a persistent server that:

• Runs telebiz-mcp internally
• Keeps browser connection alive
• Exposes HTTP API on port 9718

4. Enable MCP in Telebiz

In telebiz.io: Settings → Agent → Local MCP

The status should show "Connected" once the server is running.

4. Verify connection

# Quick health check
cd ~/clawd/skills/telebiz-mcp
npm run health

# Should show:
# 📱 Telebiz MCP Status
# ────────────────────
# Relay: ✅ Running
# Executor: ✅ Connected
# Tools: 31 available

5. Test via mcporter

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

Health Monitoring

Manual Check

# Check status
npm run health

# JSON output for automation
node dist/health.js --json

Monitor Script

The monitor tracks state changes and can be used with 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

Exit codes:

• 0 = Healthy (relay up, executor connected)
• 1 = Degraded (relay up, executor disconnected)
• 2 = Down (relay not running)
• 3 = State changed (for alerting)

Cron Integration

Add to crontab for periodic monitoring:

# 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 Integration

Add to HEARTBEAT.md for Clawdbot monitoring:

### Telebiz MCP (every 2h)
- [ ] Run: `cd ~/clawd/skills/telebiz-mcp && npm run health`
- [ ] If degraded/down: Alert Albert via Telegram

Available Tools

Chat Tools

| Tool | Description | |------|-------------| | listChats | List chats with filters (type, unread, archived, etc.) | | getChatInfo | Get detailed chat information | | getCurrentChat | Get currently open chat | | openChat | Navigate to a chat | | archiveChat | Archive a chat | | unarchiveChat | Unarchive a chat | | pinChat | Pin a chat | | unpinChat | Unpin a chat | | muteChat | Mute notifications | | unmuteChat | Unmute notifications | | deleteChat | Delete/leave chat ⚠️ |

Message Tools

| Tool | Description | |------|-------------| | sendMessage | Send text message (markdown supported) | | forwardMessages | Forward messages between chats | | deleteMessages | Delete messages ⚠️ | | searchMessages | Search globally or in a chat | | getRecentMessages | Get message history | | markChatAsRead | Mark all messages as read |

Folder Tools

| Tool | Description | |------|-------------| | listFolders | List all chat folders | | createFolder | Create a new folder | | addChatToFolder | Add chat to folders | | removeChatFromFolder | Remove chat from folders | | deleteFolder | Delete a folder ⚠️ |

Member Tools

| Tool | Description | |------|-------------| | getChatMembers | List group/channel members | | addChatMembers | Add users to group | | removeChatMember | Remove user from group | | createGroup | Create a new group |

User Tools

| Tool | Description | |------|-------------| | searchUsers | Search by name/username | | getUserInfo | Get user details |

Batch Tools

| Tool | Description | |------|-------------| | batchSendMessage | Send to multiple chats | | batchAddToFolder | Add multiple chats to folder | | batchArchive | Archive multiple chats |

Usage Examples

Find chats waiting for my reply

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

Find stale conversations I started

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

Search all messages

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

Search in specific chat

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

Send message

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

Get recent messages

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

Paginate through history

# 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

Organize chats

# List folders
mcporter call telebiz.listFolders

# Add chats to folder
mcporter call telebiz.batchAddToFolder chatIds='["-1001234","-1001235"]' folderId:5

Rate Limiting

The browser enforces rate limits to prevent Telegram flood protection:

• Max calls per request: 20
• Max calls per minute: 30
• Min delay between calls: 500ms
• Delay for heavy operations (send/forward/delete): 1s

(These values come from the Telebiz UI and are the effective limits we observed in practice.)

Known Issues / Workarounds (Feb 2026)

batchAddToFolder fails for multiple chatIds

Observed behavior:

• batchAddToFolder(folderId, chatIds=[one]) works (or reports alreadyIncluded)
• batchAddToFolder(folderId, chatIds=[two or more]) fails with: "Error: Failed to update folder"
• Repro confirmed for both:

- Auto + another group - Auto + a private chat

Workaround: loop sequentially:

• addChatToFolder(chatId=A, folderIds=[folderId])
• addChatToFolder(chatId=B, folderIds=[folderId])

linkEntityToChat is unstable / schema mismatch

Observed behavior (Feb 2026):

• linkEntityToChat returns "Validation error" for entityType=deal, contact, and company.
• In one run, using entityType="organization" successfully linked a HubSpot company to a chat — but later organization also returned "Validation error".

...