Telegram Bridge MCP server

mcp-telegram-bridge

Controlled Telegram channel bridge for any MCP host.

A small stdio Model Context Protocol server that sits between your local agent (Cursor, Claude Desktop, Windsurf, Grok/Cursor agents, and others) and the Telegram Bot API. The agent owns conversation logic; this process handles I/O, always-on outbound scrubbing, and chat allowlist enforcement. Optional strict inbound classification is disabled by default.

Built for client-owned deployments: the bridge runs on your machine, not on a hosted Grok VM. Games and game-master flows are one demo use case, not the product.

Owner context: Antonio Castellon / Castellon.CH - Swiss freelance architect. The same bridge shape is useful for SME lab patterns (notify channels, specialist handoff, moderated drafts) alongside email or ERP connectors.

What / why

Agents are good at reasoning and poor at holding a raw Bot API session by themselves. Telegram is a convenient human surface (groups, buttons, mobile). This project gives you a narrow, reviewable bridge:

• Client-owned - stdio MCP on the workstation or CI runner that already hosts your agent.
• Host-agnostic - any MCP client that can launch a local command.
• Controlled - outbound scrubbing and optional ALLOWEDCHATIDS; optional strict inbound classification for untrusted groups.
• Minimal tools - send, edit markup, answer callbacks, get updates, getMe / getChat. No game engine, no inbox file, no wake-RPC.

Pitch pattern for SMEs: start with a Telegram notify or triage channel using the same architecture you would later apply to email or ERP.

Architecture

+---------------------------+
  |  MCP host / agents        |  Cursor / Claude Desktop / Windsurf / ...
  |  (conversation logic)     |
  +-------------+-------------+
                |
                |  MCP (stdio)
                v
  +---------------------------+
  |  mcp-telegram-bridge      |  tools + safety scrub/classify
  |  (this process)           |
  +-------------+-------------+
                |
                |  HTTPS Bot API
                v
  +---------------------------+
  |  api.telegram.org         |
  +-------------+-------------+
                v
         Telegram chats / groups

The agent owns polling offsets, handoffs between specialists, and product policy. This server enforces destination controls and sends scrubbed text; inbound classification is opt-in.

Install

Requirements: Python 3.11+, a Telegram bot token from @BotFather.

git clone https://github.com/antonio-castellon/mcp-telegram-bridge.git
cd mcp-telegram-bridge
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env        # set TELEGRAM_BOT_TOKEN (never commit .env)

Or without cloning, once published:

uvx --from mcp-telegram-bridge mcp-telegram-bridge
# or: pipx run mcp-telegram-bridge

Cursor / Claude Desktop (mcp.json)

Example for Cursor (User MCP settings) or Claude Desktop (claudedesktopconfig.json):

{
  "mcpServers": {
    "telegram-bridge": {
      "command": "uvx",
      "args": ["--from", "mcp-telegram-bridge", "mcp-telegram-bridge"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN_HERE",
        "ALLOWED_CHAT_IDS": "-1001234567890"
      }
    }
  }
}

On Windows, point command at your venv Python if needed, for example:

C:\DEV.Personal\mcp-telegram-bridge\.venv\Scripts\python.exe

Leave ALLOWEDCHATIDS empty only if you intentionally accept traffic from every chat the bot can see - document that risk for your deployment.

Smoke without a host:

python -m mcp_telegram_bridge
# process waits on stdio for MCP JSON-RPC (Ctrl+C to stop)

Shortened. The full README is on GitHub.