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

Message Tools

Folder Tools

Member Tools

User Tools

Batch Tools

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".

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

# 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

mcporter Config

Located at ~/clawd/config/mcporter.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