telegram-mcp-bridge

# Telegram MCP Bridge 🤖 A self-hosted bridge that connects a **Telegram bot** to **Claude Code** over the Model Context Protocol (MCP), with an **instant auto-reply** layer so the bot answers users immediately — even when the Claude app is closed. ## Features ✨ - **Instant auto-replies** — any message to the bot gets an AI reply in ~2 seconds (OpenAI-compatible LLM) - **Claude integration** — messages containing a keyword (default: `claude`) are routed to Claude Code for full-powered answers - **Emoji reactions** — automatically reacts to every incoming message 👍❤️🔥 - **Photo support + vision** — when someone sends a photo, the bot reacts, analyzes the image content with a vision model, and replies with a description 📷👁️ - **User feedback buttons** — every bot reply has 👍 / 👎 / 🚩 Report buttons; reports are sent to the admin 👍👎🚩 - **Per-chat context** — each user only sees their own conversation history - **History persistence** — conversations survive restarts (saved to `.history.json`) - **Allowlist support** — optional: restrict usage to specific Telegram user IDs - **SSE MCP server** — Claude connects over `http://127.0.0.1:8765/sse` - **Startup launcher** — runs at login, always available - **Cloudflare Worker fallback (optional)** — always-on layer that answers via Gemini when your PC is off (see [`telegram-worker/`](telegram-worker/README.md)) ☁️ ## Architecture 🏗️ ``` Telegram bot ←→ bridge (node) ←→ LLM (auto-reply, instant) │ └── MCP over SSE ←→ Claude Code (smart mode) (optional) Telegram webhook → Cloudflare Worker → local bridge (if online) or Gemini fallback ``` ## Setup 🚀 ### Prerequisites - Node.js 18+ - A Telegram bot token (from [@BotFather](https://t.me/BotFather)) - An OpenAI-compatible LLM endpoint + API key ### Install ```bash npm install cp config.env.example config.env # edit config.env with your values ``` ### Run (manual) ```bash node server.js ``` ### Run (auto-start at login, Windows) Create a `.bat` in the Startup folder (`shell:startup`) that sets the env vars from `config.env` and runs `node server.js`. ### Connect Claude Code Add to `~/.claude.json`: ```json { "mcpServers": { "telegram": { "type": "sse", "url": "http://127.0.0.1:8765/sse" } } } ``` ## Configuration ⚙️ See `config.env.example` for all options: bot token, allowlist, SSE port, auto-reply model, fallback model, Claude keyword, vision model, admin ID. For the optional Cloudflare Worker layer, see [`telegram-worker/README.md`](telegram-worker/README.md). ## Security 🔒 - **Never commit `config.env`** — it contains your bot token and API keys - Allowlist (`ALLOWED_USER_IDS`) restricts who can use the bot — recommended for private bots - The auto-reply uses your LLM API key — a public bot means anyone can consume your quota ## License 📄 MIT