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

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

Available Tools

Chat Tools

listChats

getChatInfo

getCurrentChat

openChat

archiveChat

unarchiveChat

pinChat

unpinChat

muteChat

unmuteChat

deleteChat

Message Tools

sendMessage

forwardMessages

deleteMessages

searchMessages

getRecentMessages

markChatAsRead

Folder Tools

listFolders

createFolder

addChatToFolder

removeChatFromFolder

deleteFolder

Member Tools

getChatMembers

addChatMembers

removeChatMember

createGroup

User Tools

searchUsers

getUserInfo

Batch Tools

batchSendMessage

batchAddToFolder

batchArchive

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

TELEBIZ_PORT

9716

TELEBIZ_RELAY_URL

ws://localhost:9716

TELEBIZ_STATE_FILE

~/.telebiz-mcp-state.json

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