TeleBotHost MCP Server

A production-ready Model Context Protocol server for the TeleBotHost Developer API.

Runs locally via stdio — exposes 48 tools covering 100% of the TeleBotHost Developer API (47/47 endpoints) to any MCP-compatible AI client (Claude Desktop, Cursor, Continue, Cline, etc.).

⚠️ Important: Why Local stdio (Not Cloud Hosted)

The TeleBotHost API is protected by Cloudflare bot detection, which blocks requests from datacenter IPs. This means:

This is why the server runs locally via stdio — the standard MCP deployment pattern. Your AI client (Claude Desktop, Cursor) launches the server as a subprocess, and it makes API requests from your IP.

💡 Advanced: An HTTP server mode (server.ts) is included for self-hosting on residential connections. See HTTP Server Mode below.

Related MCP server: Telegram Bot MCP Server

✨ Features

• 🔧 48 Tools — 100% coverage of the TeleBotHost Developer API (47/47 endpoints + 1 quota helper)

• 🏠 Runs Locally — stdio transport, uses your residential IP, no Cloudflare issues

• 🔐 Secure — API key in env var (set in client config), never transmitted over network

• ⚡ Resilient — Automatic 429 retry with exponential backoff, rate-limit header tracking

• 📦 Binary-Safe — Base64-encoded ZIP download/upload for download_bot and import_bot

• 🛡️ Safe by Design — Broadcast tool requires explicit confirm: true flag

• 🧪 Tested — Compliance test suite verifies MCP spec adherence

• 🎯 Type-Safe — Strict TypeScript throughout, clean compile

• 📦 Zero-Config Install — Just npx telebothost-mcp or npx github:sahilxteam/telebothost-mcp

🚀 Quick Start

1. Get your TeleBotHost API key

1. Log in to TeleBotHost

2. Go to Developer Settings → API Keys

3. Generate a key:

   • sk_* — Secret key (full write access) — keep private

   • pub_* — Public key (read-only) — safe for client-side

2. Add to your AI client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "telebothost": {
      "command": "npx",
      "args": ["-y", "github:sahilxteam/telebothost-mcp"],
      "env": {
        "TELEBOTHOST_API_KEY": "sk_your_key_here"
      }
    }
  }
}

Note: Replace github:sahilxteam/telebothost-mcp with telebothost-mcp once published to npm.

Cursor

Settings → MCP → Add Server:

{
  "mcpServers": {
    "telebothost": {
      "command": "npx",
      "args": ["-y", "github:sahilxteam/telebothost-mcp"],
      "env": {
        "TELEBOTHOST_API_KEY": "sk_your_key_here"
      }
    }
  }
}

VS Code (with Cline / Continue)

Add to your MCP settings:

{
  "mcp.servers": {
    "telebothost": {
      "command": "npx",
      "args": ["-y", "github:sahilxteam/telebothost-mcp"],
      "env": {
        "TELEBOTHOST_API_KEY": "sk_your_key_here"
      }
    }
  }
}

3. Restart & use

Restart your AI client. Try prompts like:

• "List my TeleBotHost bots"

• "Create a new command called /start on bot 12345"

• "Browse the community store and show me the top 5 bots"

• "What's my current API quota?"

📦 Alternative: Local Clone

If you prefer to clone the repo (for development or customization):

git clone https://github.com/sahilxteam/telebothost-mcp.git
cd telebothost-mcp
npm install

Then in your client config, point to the local clone:

{
  "mcpServers": {
    "telebothost": {
      "command": "node",
      "args": ["--import", "tsx", "/absolute/path/to/telebothost-mcp/bin/mcp.ts"],
      "env": {
        "TELEBOTHOST_API_KEY": "sk_your_key_here"
      }
    }
  }
}

🛠️ Available Tools (48)

🩺 Health (1)

🌐 Public Discovery (8) — no auth required

🤖 Bot Lifecycle (20) — sk_* key required for writes

💾 Bot Storage (4)

📢 Broadcasts (6)

⚡ Commands (5)

🛍️ Community Store (2)

📊 Quota (1)

🔌 MCP Protocol

This server implements the Model Context Protocol stdio transport — the standard for local AI client integration.

JSON-RPC 2.0 Methods Supported

Stdio Design

• The AI client launches the server as a subprocess

• Client writes JSON-RPC requests to the server's stdin

• Server writes JSON-RPC responses to stdout

• Server writes logs/diagnostics to stderr

• Single-user, single-session — no auth headers needed

• API key read from TELEBOTHOST_API_KEY env var (set in client config)

🚨 Error Handling

Layer 1: Protocol Errors (JSON-RPC)

Layer 2: Tool Errors (MCP isError)

When the upstream TBH API returns an error, the response includes isError: true:

{
  "content": [{
    "type": "text",
    "text": "TeleBotHost API error 429: Rate limit exceeded. Retry after 60s."
  }],
  "isError": true
}

Layer 3: Automatic Retry

HTTP 429 responses from the TBH API are automatically retried up to 3 times with exponential backoff (2s, 4s, 8s).

Layer 4: Cloudflare Detection

If you accidentally run in a datacenter environment, the client detects Cloudflare challenge responses (HTTP 403 + cf_chl in body) and returns a clear error message instead of the raw HTML challenge page.

🧪 Testing

Compliance Test Suite

# Test the stdio server
npm test

# Or test an HTTP deployment (advanced)
MCP_URL=http://localhost:3000/api/mcp bash scripts/test-mcp.sh

What it verifies:

1. initialize handshake returns correct protocol version & server info

2. ping returns a result

3. tools/list returns exactly 48 tools

4. All tools have name + description + inputSchema

5. All tools use clean names (no telebothost_ prefix)

6. tools/call rejects unknown tools with error -32602

7. All required tools are present (10 critical tools checked)

Manual Smoke Test

# Test stdio directly
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | \
  TELEBOTHOST_API_KEY=sk_your_key node --import tsx bin/mcp.ts

📊 API Coverage

This MCP server covers 100% of the TeleBotHost Developer API — every endpoint in the OpenAPI 3.0.3 spec is mapped to a tool.

Binary Endpoints

Two endpoints involve binary data (ZIP files), handled via base64 encoding:

🔧 Environment Variables

In stdio mode, there is no MCP_AUTH_TOKEN — the server is single-user and access is controlled by your local machine.

⏱️ Rate Limits

The TeleBotHost API enforces plan-based limits. This MCP server automatically retries on HTTP 429 with exponential backoff.

pub_* keys are always capped at 1,000/day, 15/min, 15,000/month regardless of plan.

Use get_quota to check remaining quota at any time.

💻 HTTP Server Mode (Optional)

⚠️ Only works on residential IPs. Cloud hosting (Vercel/Render/Railway/Fly) will be blocked by Cloudflare.

For self-hosting on a home server or VPS with residential IP, an HTTP server mode is included:

# Install
git clone https://github.com/sahilxteam/telebothost-mcp.git
cd telebothost-mcp
npm install

# Set env vars
export TELEBOTHOST_API_KEY=sk_your_key_here
# Optional: export MCP_AUTH_TOKEN=your-mcp-access-token

# Start HTTP server on port 3000
npm run serve:http

HTTP Endpoints

HTTP Auth (Two Layers)

📁 Project Structure

telebothost-mcp/
├── bin/
│   ├── mcp.js              # Entry point shim (loads tsx, runs mcp.ts)
│   └── mcp.ts              # stdio MCP server (primary entry point)
├── lib/
│   ├── types.ts            # Shared types & TbhApiError
│   ├── client.ts           # TeleBotHost API client (auth, retry, binary, errors)
│   ├── tools.ts            # All 48 MCP tool definitions
│   └── docs.ts             # HTML docs page generator (for HTTP mode)
├── scripts/
│   └── test-mcp.sh         # Compliance test suite
├── server.ts               # HTTP server (optional, self-hosting only)
├── render.yaml             # Render.com Blueprint (with Cloudflare warning)
├── .env.example            # Environment variable template
├── .nvmrc                  # Node version pin
├── package.json            # bin field → ./bin/mcp.js
├── tsconfig.json
├── LICENSE
├── CONTRIBUTING.md
└── README.md

💻 Local Development

# Install deps
npm install

# Set env var
cp .env.example .env
# Edit .env with your TELEBOTHOST_API_KEY

# Run stdio server (primary mode)
npm start

# Run HTTP server (advanced, for testing docs page)
npm run serve:http
# → http://localhost:3000

# Type-check
npm run typecheck

# Run compliance tests
npm test

🗺️ Roadmap

• v1.0.0 — Initial release: 46 tools, Vercel deployment

• v1.1.0 — Cleaner tool names (dropped telebothost_ prefix)

• v1.2.0 — 100% API coverage: added download_bot & import_bot, compliance test suite

• v1.3.0 — Per-request API key via X-Tbh-Api-Key header (HTTP mode)

• v1.4.0 — Pivot to stdio (local run) — removed Vercel/Render as primary options due to Cloudflare bot detection blocking datacenter IPs

• v1.5.0 — Publish to npm, Docker support, GitHub Actions CI

• v2.0.0 — Cloudflare Workers transport (whitelisted by Cloudflare)

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for setup, conventions, and PR guidelines.

📄 License

MIT © Cyber X

🔗 Links

• TeleBotHost: telebothost.com

• Developer API Docs: api.telebothost.com/api/v1/docs

• MCP Specification: modelcontextprotocol.io

• Issues: GitHub Issues

Built with ❤️ for the TeleBotHost community