mcp-telegram-bridge

Stdio MCP bridge to the Telegram Bot API, with fail-closed chat admission and outbound scrubbing.

A small Model Context Protocol server that a local agent (Cursor, Claude Desktop, Windsurf, and others) launches on your machine. The agent owns the conversation. This process does Bot API I/O, scrubs outbound secrets, and refuses chats you have not allowed.

Version 0.2.0 changes admission: an empty allowlist denies every chat. Set ALLOWED_CHAT_IDS, or opt in to open mode with ALLOW_ALL_CHATS=1.

Built for client-owned deployments. The bridge is not a hosted bot service. Games and game-master flows are one demo use case, not the product.

Owner: Antonio Castellon / Castellon.CH.

Quick start

Requirements: Python 3.11+, a bot token from @BotFather, and the numeric id of the chat you want the bot to use.

git clone https://github.com/antonio-castellon/mcp-telegram-bridge.git
cd mcp-telegram-bridge
uv sync --extra dev          # or: python -m venv .venv && pip install -e ".[dev]"
cp .env.example .env         # set TELEGRAM_BOT_TOKEN and ALLOWED_CHAT_IDS
uv run mcp-telegram-bridge   # waits on stdin for MCP JSON-RPC; Ctrl+C to stop

uv.lock pins every dependency with hashes. CI installs from that lock (uv sync --frozen). pip install -e ".[dev]" still works and uses the version ranges in pyproject.toml.

Cursor or Claude Desktop (mcp.json / claude_desktop_config.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"
      }
    }
  }
}

Do not commit a real token. Leave ALLOW_ALL_CHATS unset.

Use as a Python library

The same operations are available without the MCP server. import mcp_telegram_bridge loads TelegramBridge and Settings only. It does not import the mcp package. Pass Settings directly; Settings.from_env() is the default when you want the environment variables above.

import asyncio

from mcp_telegram_bridge import Settings, TelegramBridge

async def main() -> None:
    settings = Settings(
        bot_token="YOUR_BOT_TOKEN_HERE",
        allowed_chat_ids=frozenset({-1001234567890}),
    )
    bridge = TelegramBridge(settings)
    await bridge.get_me()
    await bridge.send_message(
        -1001234567890,
        "hello",
        buttons=[{"id": "ack", "label": "Ack"}],
    )
    await bridge.get_updates(timeout=0)
    await bridge.aclose()

asyncio.run(main())

TelegramBridge(Settings.from_env()) reads TELEGRAM_BOT_TOKEN, ALLOWED_CHAT_IDS, and the other variables. The CLI still prints access-mode warnings to stderr. Library callers can use mcp_telegram_bridge.config.emit_startup_warnings if they want the same lines. The mcp-telegram-bridge command is unchanged.

Configuration

... View full README on GitHub