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