The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Telegram Bridge listing page.
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.
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:
ALLOWED_CHAT_IDS; optional strict inbound classification for untrusted groups.Pitch pattern for SMEs: start with a Telegram notify or triage channel using the same architecture you would later apply to email or ERP.
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.
Requirements: Python 3.11+, a Telegram bot token from @BotFather.
Or without cloning, once published:
mcp.json)Example for Cursor (User MCP settings) or Claude Desktop (claude_desktop_config.json):
On Windows, point command at your venv Python if needed, for example:
C:\DEV.Personal\mcp-telegram-bridge\.venv\Scripts\python.exe
Leave ALLOWED_CHAT_IDS empty only if you intentionally accept traffic from every chat the bot can see - document that risk for your deployment.
Smoke without a host:
| Tool | Purpose |
|---|---|
telegram_get_me | Bot identity / connectivity check |
telegram_send_message | chat_id, text, optional parse_mode, optional buttons=[{id,label}] |
telegram_edit_reply_markup | Strip or replace inline buttons |
telegram_answer_callback | Ack a callback_query_id (optional toast) |
telegram_get_updates | offset, limit, timeout - returns messages + callback_queries; agent owns the loop |
telegram_get_chat | Chat metadata |
Outbound text is always scrubbed. ALLOWED_CHAT_IDS restricts destinations when configured. telegram_get_updates runs the heuristic secret/NSFW classifier only when SAFETY_STRICT=1 (or true/yes/on); strict mode is optional and recommended for public or untrusted groups.
Run one bridge process per bot (or one bot with clear agent roles). Use the group for standup notes, triage queues, and handoff between specialist agents ("ops acknowledges; billing drafts the reply"). Keep humans in the loop for irreversible actions.
Send scene text with buttons=[{id,label}, ...] for player choices; on callback_query, answer the callback, optionally claim-style first-tap handling in the agent, then edit markup to clear spent choices. This is a demo of buttons + agent loop - not a bundled RPG engine.
Push alerts with ack buttons (ack, snooze, escalate). The agent records who tapped what; Telegram is the pager surface, not the source of truth.
Draft replies and suggest actions. Humans still own ban / restrict / delete in Telegram Admin - say so in your agent prompt. The bridge must not be treated as a moderation authority.
Same shape as an email or ERP connector: narrow tools, allow-listed destinations, scrubbed egress, explicit inbound warnings. Telegram is the demo channel; swap the transport later without rewriting agent policy.
Optional context only - this project does not require them:
SAFETY.md and safety.pymcp-telegram-bridge is the reusable, host-agnostic extraction: I/O + safety, no game loop and no Grok VM wake logic.
See SAFETY.md for the threat model, always-on scrubbing and allowlist controls, token handling, optional strict mode, and button-map data dir (MCP_TELEGRAM_BRIDGE_DATA_DIR, modes 0700/0600). Do not put secrets in the repository; prefer ALLOWED_CHAT_IDS in production-like setups.
Tests mock Telegram HTTP with respx / httpx; no live token required.
Canonical name: io.github.antonio-castellon/mcp-telegram-bridge
Also listed on mcpservers.org and MCP Marketplace.
For marketplace listing autofill, see LAUNCHGUIDE.md (tagline, setup env vars, category, use cases, and example prompts).
MIT (c) Antonio Castellon / Castellon.CH