Telegram Bridge MCP

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

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

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.

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

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:

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:

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

License

AGPL-3.0-only