Telegram Bridge MCP Server

Telegram Bridge MCP

Two-way Telegram bridge for AI agents — messaging, voice, multi-session, real-time.

A Model Context Protocol server that connects AI assistants to Telegram. Send messages, ask questions, receive voice replies, run multiple agent sessions concurrently — all through a single bot.

Works with VS Code Copilot, Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible host.

Highlights

• Two-way messaging — text, Markdown, files, voice notes
• Interactive controls — buttons, confirmations, checklists, progress bars
• Voice in, voice out — automatic transcription (Whisper) and TTS (local or OpenAI)
• Multi-session — multiple agents share one bot with per-session queues, identity auth, and message routing
• Reminders — scheduled events that fire as synthetic messages after a delay
• Live animations — cycling status messages while the agent works
• Slash commands — dynamic bot menu; commands arrive as structured events
• No webhooks — long-polling, no public URL needed

Quick Start

1. Install

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

Or use the pre-built Docker image — no Node.js required.

2. Create a Telegram bot

Message @BotFather → /newbot → copy the token.

3. Pair

pnpm pair

Verifies your token, generates a pairing code, waits for you to send it to the bot, then writes .env.

4. Configure your MCP host

See mcp-config.example.json for a complete reference. The core shape for each host:

VS Code (.vscode/mcp.json):

{
  "servers": {
    "telegram": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/telegram-bridge-mcp",
      "env": { "BOT_TOKEN": "...", "ALLOWED_USER_ID": "..." }
    }
  }
}

Claude Desktop (claude_desktop_config.json) / Claude Code (.mcp.json):

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/absolute/path/to/telegram-bridge-mcp/dist/index.js"],
      "env": { "BOT_TOKEN": "...", "ALLOWED_USER_ID": "..." }
    }
  }
}

Do not add to global ~/.claude.json — multiple instances will fight over getUpdates.

5. Start

Paste LOOP-PROMPT.md into your AI assistant's chat. It connects, announces itself on Telegram, and waits for instructions.

Tools

Interaction

Messaging

send_message · send_choice · edit_message · edit_message_text · append_text · delete_message · pin_message · send_file · show_typing · send_chat_action · answer_callback_query · get_message · get_chat_history

Session

Reminders

Utilities

get_me · get_chat · get_agent_guide · get_debug_log · set_reaction · set_commands · set_topic · set_default_animation · set_voice · download_file · transcribe_voice · shutdown

Multi-Session

Multiple agents can share one bot simultaneously. Each ses