Telebiz Mcp

# 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

```bash 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

```bash 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

```bash # 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

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

Health Monitoring

Manual Check

```bash # 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:

```bash # 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:

```bash # 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:

• ```markdown
• ### 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 ```bash mcporter call telebiz.listChats iAmLastSender=false hasUnread=true limit:20 ```

Find stale conversations I started ```bash mcporter call telebiz.listChats iAmLastSender=true lastMessageOlderThanDays:7 limit:20 ```

Search all messages ```bash mcporter call telebiz.searchMessages query="invoice" limit:20 ```

Search in specific chat ```bash mcporter call telebiz.searchMessages query="meeting" chatId=-1001234567890 limit:10 ```

Send message ```bash mcporter call telebiz.sendMessage chatId=-1001234567890 text="Hello from Clawdbot!" ```

Get recent messages ```bash mcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50 ```

Paginate through history ```bash # 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 ```bash # 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"**.

Implication: this tool is either behind a feature flag, has changing server-side validation, or the published schema/enums don’t match what the backend expects.

• Workaround:
• Prefer linking via `createContact/createDeal/createCompany` (these link to the chat at creation time).
• Use `associateEntities` to connect deal↔company/contact.
• Don’t depend on `linkEntityToChat` until upstream provides a stable contract + better error messages.

Troubleshooting

Relay not starting ```bash # Check if port is in use ss -tlnp | grep 9716

# Kill existing process pkill -f "relay.js"

# Start fresh ./start-relay.sh ```

Browser not connecting 1. Verify relay is running: `npm run health` 2. Check browser console (F12) for WebSocket errors 3. Ensure MCP is enabled in Settings → Agent → Enable MCP 4. Try refreshing the telebiz-tt page

"Executor not connected" error The browser tab with telebiz-tt must be: - Open and visible (not suspended) - Logged into Telegram - MCP enabled in settings

Rate limit errors - Reduce batch sizes - Add delays between operations - Be more specific in filters to reduce API calls

Session expired If Telegram session expires: 1. Refresh the telebiz-tt browser page 2. Re-login if prompted 3. Re-enable MCP in settings

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | `TELEBIZ_PORT` | `9716` | Relay WebSocket port | | `TELEBIZ_RELAY_URL` | `ws://localhost:9716` | Relay URL for MCP server | | `TELEBIZ_STATE_FILE` | `~/.telebiz-mcp-state.json` | Monitor state file |

mcporter Config

Located at `~/clawd/config/mcporter.json`:

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

Note: Use the HTTP URL (not stdio) to avoid spawning conflicts.

Security Notes

• The browser holds your Telegram session - keep it secure
• Don't expose the relay port (9716) to the internet
• Review tool calls before executing destructive operations
• Rate limits help prevent accidental spam