Telebiz Mcp

Access Telegram data via MCP using the telebiz-tt browser client. Lists chats, reads messages, searches, manages folders, and sends messages through an authenticated Telegram session.

Security Scan

The skill's files and instructions are coherent with its stated purpose (bridging a logged-in telebiz browser to an MCP API), but it exposes a locally-running, persistent service in ways that can be accidentally reachable from the network (CORS: *, binds to all interfaces), and includes scripts that create persistent daemons — this combination increases the risk of exposing your authenticated Telegram session if you install it without hardening.

Purpose & Capability

Name/description match the implementation: code provides a relay (WebSocket), HTTP wrapper, daemon, and MCP stdio server to use telebiz-tt (browser executor) as an authenticated Telegram toolset. The npm package dependency and use of a 'telebiz-mcp' subprocess is consistent with the described architecture.

Instruction Scope

Runtime instructions ask you to install the telebiz package, open telebiz.io in a browser, and start local servers. The code does additional actions not highlighted prominently in SKILL.md: it writes PID/log/state files to your HOME, auto-restarts subprocesses, and exposes an HTTP API and WebSocket relay. Those behaviors are plausible for the described function but SKILL.md does not warn that the HTTP/WebSocket servers bind to all network interfaces or that CORS is set to '*', which can expose an authenticated session beyond localhost if the host is reachable.

Install Mechanism

There is no registry install spec in the skill bundle, but SKILL.md tells users to npm install -g @telebiz/telebiz-mcp (a normal approach). The bundled package.json and source files show only standard dependencies (@modelcontextprotocol/sdk and ws). No external arbitrary download URLs or obfuscated code were observed in the provided files.

Credentials

The skill does not require credentials or secrets. It reads conventional env vars (HOME and optional TELEBIZ_* variables to override ports/paths). No unrelated credentials or broad secret access are requested.

Persistence & Privilege

The code installs/starts long-running processes (daemon, HTTP server, relay), writes PID/state/log files in the user's HOME and auto-restarts the MCP subprocess. There is also a telebiz-service.sh file (likely for system service installation) — SKILL.md suggests running start scripts. Persistent daemons combined with network-listening services increase attack surface; the skill is not force-included (always:false) but will create persistent presence if you follow the setup.

What to consider before installing

This skill appears to do what it claims (bridge an authenticated telebiz browser session to an MCP API), but take precautions before installing: - Network exposure: by default the relay and HTTP server bind to all interfaces (0.0.0.0) and the HTTP server sets Access-Control-Allow-Origin: *. That means if your machine is reachable on the network, remote hosts could talk to the service and indirectly act using your logged-in Telegram session. Only run this on a trusted, firewalled host or change bindings to 127.0.0.1. - Limit interfaces: set TELEBIZ_HTTP_PORT/TELEBIZ_PORT/TELEBIZ_RELAY_URL or edit the server code to listen only on 127.0.0.1, or run the service inside a local-only container or VM. - Review startup scripts: inspect start-http.sh, start-relay.sh, and telebiz-service.sh before running them — telebiz-service.sh may install a systemd service or otherwise create persistent system-level configuration. - Principle of least privilege: do not run as root. Keep the service confined to a dedicated user or container. - Authenticate and audit: the skill will be able to read and send messages using your authenticated browser session — treat it like any other app with access to your account. Only install if you trust the telebiz package source and the skill code; consider running it in an isolated environment first. - If you want to proceed: change the server listen calls to bind to 127.0.0.1 (or add host argument), remove or tighten the CORS wildcard, and ensure your firewall blocks external access to ports 9716/9717/9718 (or whichever you use). If you cannot validate the telebiz package origin or you need to expose functionality to other hosts, audit the code carefully and prefer running it inside a network-restricted container/VM.

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

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

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

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

• 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