Telegram Bridge MCP

No Claw? No Problem.

Anthropic restricted Claude Code's native instance API — but this bridge doesn't care. It's a standard Model Context Protocol server. Any IDE, any model, any agent framework that speaks MCP connects out of the box — no proprietary lock-in, no webhooks, no public URL required.

What Is This?

Telegram Bridge MCP connects AI assistants to Telegram bidirectionally. It lets any MCP-compatible client send messages, ask questions, receive voice replies, and run multiple concurrent agent sessions — all through a single bot you control.

Works with: VS Code (GitHub Copilot Chat), Claude Code, Cursor, Windsurf, Copilot CLI, and any MCP-compatible host.

Highlights

| Feature | Description | | --- | --- | | Two-way messaging | Text, Markdown, files, voice notes | | Interactive controls | Inline buttons, confirmations, questions | | Super tools | Self-pinning checklists and emoji progress bars that update in-place | | Voice | Auto-transcription (bundled Whisper ONNX, no ffmpeg) + TTS (local Kokoro, OpenAI, or bundled ONNX) | | Multi-session | Multiple agents share one bot with isolated queues, token auth, and color identity | | Animations | Cycling status frames while your agent works | | Reminders | Scheduled synthetic events delivered via dequeue | | Slash commands | Dynamic bot menu; commands arrive as structured events | | No webhooks | Pure long-polling — no public URL, no reverse proxy |

Quick Start

Tip: If your AI has web access, paste this to get started (requires web access):

Set me up: https://github.com/electricessence/Telegram-Bridge-MCP

1. Clone and build

git clone https://github.com/electricessence/Telegram-Bridge-MCP.git
cd Telegram-Bridge-MCP
pnpm install && pnpm build

2. Create a bot

Message @BotFather on Telegram:

/newbot

Copy the token it gives you.

3. Pair interactively

pnpm pair

The wizard prompts for your bot token and Telegram user ID, writes a .env file, and verifies connectivity.

4. Configure your MCP host

See docs/setup.md for per-client config snippets (VS Code, Claude Code, Cursor, Docker).

Transports

| Transport | Entry Point | Best For | | --- | --- | --- | | Streamable HTTP | pnpm start -- --http | Multiple clients sharing one server (recommended) | | stdio | node dist/index.js | Single client, no persistent server | | Launcher bridge | node dist/launcher.js | Auto-starts HTTP if needed, bridges stdio ↔ HTTP |

Claude Code / Cursor / other MCP hosts

{
  "mcpServers": {
    "telegram": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3099/mcp"
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "telegram": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3099/mcp"
    }
  }
}

Claude Code / Cursor / other MCP hosts

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/path/to/Telegram-Bridge-MCP/dist/index.js"],
      "env": {
        "BOT_TOKEN": "your-token",
        "ALLOWED_USER_ID": "your-user-id"
      }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "telegram": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/Telegram-Bridge-MCP/dist/index.js"],
      "env": {
        "BOT_TOKEN": "your-token",
        "ALLOWED_USER_ID": "your-user-id"
      }
    }
  }
}

Tools — The v6 API

Version 6 consolidates the entire API into 4 tools with type-based routing. Call help(topic?) at any time for interactive documentation discovery.

send — Outbound Messaging

All outbound operations flow through a single send call. The type parameter determines behavior.

| Type | Description | | --- | --- | | text | Formatted Markdown text; pass audio: "..." to speak via TTS | | file | Photo, document, video, audio, or voice note | | notification | Status notification with severity: info · success · warning · error | | choice | Message with inline buttons (non-blocking) | | question | Blocking prompt — route with ask, confirm, or choose | | dm | DM to another session (target_sid or target alias); "direct" accepted as alias | | append | Append text to an existing message | | animation | Start a cycling status animation | | checklist | Create a self-pinning live checklist; requires title, accepts steps array of {label, status} objects | | progress | Create an emoji progress bar (width configurable) |

Update in-place with action(type: "checklist/update", message_id: ...) and action(type: "progress/update", message_id: ...) respectively. See docs/super-tools.md.

// Examples — token required for all session-scoped calls; session/start and most help topics work without a token
// token: 1234567 (required for all session-scoped calls)
send({ token: 1234567, type: "text", text: "Hello from your AI agent!" })
send({ token: 1234567, type: "notification", severity: "success", text: "Build passed." })
send({ token: 1234567, type: "question", ask: "Proceed with deployment?" })
send({ token: 1234567, type: "checklist", title: "Pipeline", steps: [{ label: "Design", status: "pending" }, { label: "Implement", status: "pending" }, { label: "Review", status: "pending" }, { label: "Deploy", status: "pending" }] })
send({ token: 1234567, type: "progress", title: "Processing files", percent: 40, subtext: "4 of 10 complete", width: 10 })

dequeue — Receive Inbound Events

Long-poll for the next inbound event: messages, button presses, voice notes, slash commands, reminders.

Note: token is the integer returned by action(type: "session/start").

dequeue({ token: 1234567 })              // default timeout — idles until event
dequeue({ token: 1234567, timeout: 0 }) // non-blocking drain (coordination gates)

action — Universal Dispatcher

RESTful path routing via type. Supports progressive discovery:

• Omit type → list all categories
• Pass a category → list sub-paths
• Pass a full path → execute

Session

session/start · session/close · session/list · session/rename · session/idle

Profile

profile/voice · profile/topic · profile/save · profile/load · profile/import · profile/dequeue-default

Reminder

reminder/set · reminder/cancel · reminder/list

Animation

animation/default · animation/cancel

Message

message/edit · message/delete · message/pin · message/route · message/history · message/get

Chat

chat/info

Super Tools

checklist/update · progress/update

Confirm Presets

confirm/ok · confirm/ok-cancel · confirm/yn

Standalone

react · acknowledge · show-typing · commands/set · logging/toggle · transcribe · download

Governor-only

approve · shutdown · shutdown/warn · log/get · log/list · log/roll · log/delete · log/debug

help — Documentation Discovery

help()                    // list all topics
help({ topic: "send" })  // targeted reference for a specific tool or type

Multi-Session

Multiple agents can share one bot simultaneously without cross-talk.

session/start → token (integer) → pass on every session-scoped call

Token format: token = sid * 1_000_000 + pin — a single integer, returned by action(type: "session/start").

| Capability | Description | | --- | --- | | Isolated queues | Per-session routing; no messages bleed between agents | | Color identity | Outbound messages prefixed with color + name (e.g., 🟩 Worker 1) | | Governor model | First session is primary; additional sessions require operator approval via color-picker keyboard | | DMs | Inter-session messaging via send(type: "dm", target_sid: N, ...) (alias: "direct"; target_sid alias: target) | | Health monitoring | Unresponsive sessions trigger operator prompts to reroute or promote | | Graceful teardown | Orphaned events rerouted; callback hooks replaced on close |

See docs/multi-session-protocol.md for the full routing protocol.

Voice

Transcription (Inbound)

Voice messages are auto-transcribed before delivery. No external API, no ffmpeg required — the Whisper ONNX model is bundled.

WHISPER_MODEL=onnx-community/whisper-base   # default
WHISPER_CACHE_DIR=/path/to/cache            # optional

Text-to-Speech (Outbound)

Triggered by send(type: "text", audio: "..."). Provider is selected automatically:

| Environment Variable | Provider | | --- | --- | | TTS_HOST | Any OpenAI-compatible /v1/audio/speech endpoint | | OPENAI_API_KEY | api.openai.com | | Neither set | Bundled ONNX model (zero config) |

Kokoro (recommended local TTS)

High-quality local TTS with 25+ voices. No API key, no cost.

docker run -d --name kokoro -p 8880:8880 ghcr.io/hexgrad/kokoro-onnx-server:latest

TTS_HOST=http://localhost:8880
TTS_FORMAT=ogg
TTS_VOICE=af_heart

Send /voice in Telegram to browse and sample voices live.

Per-session voice override: action(type: "profile/voice") or /voice in Telegram.

MCP Resources

Five resources are available to any connected client — no tool call required:

| URI | Contents | | --- | --- | | telegram-bridge-mcp://agent-guide | Behavioral guide for AI agents | | telegram-bridge-mcp://communication-guide | Communication patterns and loop rules | | telegram-bridge-mcp://quick-reference | Hard rules + compact tool table | | telegram-bridge-mcp://setup-guide | Setup walkthrough | | telegram-bridge-mcp://formatting-guide | Markdown / MarkdownV2 / HTML reference |

Docker

ghcr.io/electricessence/telegram-bridge-mcp:latest

Before running Docker: Create your .env file first by running pnpm pair on a machine with Node.js, or copy .env.example and fill it in manually.

Streamable HTTP (recommended) — run as a long-lived service:

docker run -d --name telegram-mcp \
  --env-file /absolute/path/to/.env \
  -e MCP_PORT=3099 \
  -p 3099:3099 \
  -v telegram-mcp-cache:/home/node/.cache \
  ghcr.io/electricessence/telegram-bridge-mcp:latest

Connect MCP hosts to http://127.0.0.1:3099/mcp.

{
  "command": "docker",
  "args": [
    "run", "--rm", "-i",
    "--env-file", "/absolute/path/to/.env",
    "-v", "telegram-mcp-cache:/home/node/.cache",
    "ghcr.io/electricessence/telegram-bridge-mcp:latest"
  ]
}

The cache volume persists Whisper and TTS model weights across container restarts.

Development

pnpm build      # Compile TypeScript
pnpm dev        # Watch mode
pnpm test       # Run tests
pnpm coverage   # Coverage report
pnpm pair       # Re-run pairing wizard

Agent Setup

To keep agents reliably in the Telegram dequeue loop, install the loop-guard hook for your host. The hook prevents agents from dropping out of the loop on idle or forced stop.

See docs/agent-setup.md for installation instructions for VS Code (GitHub Copilot Chat) and Claude Code.

Documentation

| Doc | Contents | | --- | --- | | docs/setup.md | Full setup walkthrough with per-client config | | docs/multi-session-protocol.md | Multi-session routing and governor model | | docs/super-tools.md | Checklist and progress bar reference | | docs/agent-setup.md | Loop-guard hooks for VS Code and Claude Code | | docs/migration-v5-to-v6.md | v5 → v6 tool name mapping | | docs/git-index-safety.md | Git index safety notes for multi-agent environments |

License

AGPL-3.0-only