# mcp-telegram-bridge [](https://mcpservers.org/servers/antonio-castellon/mcp-telegram-bridge) **Controlled Telegram channel bridge for any MCP host.** A small stdio [Model Context Protocol](https://modelcontextprotocol.io/) 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](https://castellon.ch) / 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 `ALLOWED_CHAT_IDS`; 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](https://t.me/BotFather). ```bash 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: ```bash 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 (`claude_desktop_config.json`): ```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 `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: ```bash python -m mcp_telegram_bridge # process waits on stdio for MCP JSON-RPC (Ctrl+C to stop) ``` ## MCP tools | 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. ## Usage guide ### Collaborative agents in a Telegram group 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. ### Game master / tabletop facilitator (demo) 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. ### Support / ops notify channel Push alerts with ack buttons (`ack`, `snooze`, `escalate`). The agent records who tapped what; Telegram is the pager surface, not the source of truth. ### Community moderation assistant 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. ### Lab / SME pattern 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. ## Agent Skills This MCP server pairs naturally with a companion **SKILL.md** (the open agent skills format used by Claude Code, Cursor, Codex CLI, and 20+ other agents). The skill teaches the agent when and how to use the tools, the safety controls (scrubbing, allowlist, optional strict mode), and that the agent owns the `telegram_get_updates` offset loop. Agent skill: [Telegram Bridge on Agensi](https://www.agensi.io/skills/telegram-bridge), a ready-made SKILL.md that teaches agents to use this server. The MCP server itself remains the I/O + safety layer; the skill is pure instructions. ## What this is NOT - Not a hosted bot SaaS or multi-tenant cloud bridge - Not Grok-only (works with any stdio MCP host) - Not a full RPG / game engine (no dice ruleset, no campaign DB in this repo) - Not an unattended admin bot (no ban tools shipped here) ## Relation to sibling demos Optional context only - this project does **not** require them: - [grokgame](https://github.com/antonio-castellon/grokgame) - tabletop / game demo surface - [grok2telegram](https://github.com/antonio-castellon/grok2telegram) - earlier bridge experiment whose safety doctrine informed `SAFETY.md` and `safety.py` `mcp-telegram-bridge` is the reusable, host-agnostic extraction: I/O + safety, no game loop and no Grok VM wake logic. ## Safety See **[SAFETY.md](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. ## Development ```bash pip install -e ".[dev]" pytest ``` Tests mock Telegram HTTP with `respx` / `httpx`; no live token required. ## MCP Registry Canonical name: `io.github.antonio-castellon/mcp-telegram-bridge` Also listed on [mcpservers.org](https://mcpservers.org/servers/antonio-castellon/mcp-telegram-bridge), [MCP Marketplace](https://mcp-marketplace.io/server/io-github-antonio-castellon-mcp-telegram-bridge), and (as a companion agent skill) [Agensi](https://www.agensi.io/skills/telegram-bridge). For marketplace listing autofill, see **[LAUNCHGUIDE.md](LAUNCHGUIDE.md)** (tagline, setup env vars, category, use cases, and example prompts). ## License MIT (c) Antonio Castellon / Castellon.CH