Telebiz Mcp

telebiz-mcp

MCP integration for Telegram via telebiz-tt browser client.

Quick Rules (read this first)

Architecture

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

Quick Setup

Prerequisites

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:

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:

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:

(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

Workaround: loop sequentially:

linkEntityToChat is unstable / schema mismatch

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:

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

"Executor not connected" error

Rate limit errors

Session expired

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:

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

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

Security Notes

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:

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

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

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

"Executor not connected" error

Rate limit errors

Session expired