# moeinv363/telegram-mcp-bridge architecture

> Architecture diagram of the GitHub repository moeinv363/telegram-mcp-bridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moeinv363/telegram-mcp-bridge
- Repository: https://github.com/moeinv363/telegram-mcp-bridge

## Overview

Telegram MCP Bridge is a self-hosted Telegram bot that replies immediately through an OpenAI-compatible LLM and can route keyword-triggered requests to Claude Code over MCP/SSE. Its documented workflow also includes per-chat history, photo analysis, reactions, and feedback. An optional Cloudflare Worker handles Telegram webhooks and can use Gemini when the local bridge is offline. The source index lists the main files but provides no excerpts, so relationships below rely on README statements; internal call ordering is not inferred.

Main entry points: [`server.js`](https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js) (Bridge runtime), [`telegram-worker/src/worker.js`](https://github.com/moeinv363/telegram-mcp-bridge/blob/main/telegram-worker/src/worker.js) (Telegram webhook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bridge["Local Telegram Bridge"]
  node_bridge_app["Bridge runtime<br/>[server.js]"]
  node_allowlist["Allowlist<br/>[server.js]"]
  node_reply["Instant replies<br/>[server.js]"]
  node_context["Per-chat context<br/>[server.js]"]
  node_history["History persistence<br/>[server.js]"]
  node_history_store[("History file")]
  node_photo["Photo vision<br/>[server.js]"]
  node_reactions["Emoji reactions<br/>[server.js]"]
  node_feedback["Feedback buttons<br/>[server.js]"]
end

subgraph group_mcp["Claude Integration"]
  node_mcp_endpoint["MCP SSE endpoint<br/>[server.js]"]
end

subgraph group_worker["Worker Fallback"]
  node_worker_webhook["Telegram webhook<br/>[worker.js]"]
  node_worker_fallback["Gemini fallback<br/>[worker.js]"]
end

node_user(("Telegram user"))
node_telegram["Telegram Bot API"]
node_admin(("Bot admin"))
node_llm["OpenAI-compatible LLM"]
node_vision["Vision model"]
node_claude["Claude Code"]
node_gemini["Gemini"]

node_user -->|"messages"| node_telegram
node_telegram -->|"delivers updates"| node_bridge_app
node_bridge_app -->|"restricts users"| node_allowlist
node_bridge_app -->|"auto-replies"| node_reply
node_reply -->|"requests answer"| node_llm
node_bridge_app -->|"keeps chat context"| node_context
node_context -->|"persists conversations"| node_history
node_history -->|"reads and writes"| node_history_store
node_telegram -->|"sends photos"| node_photo
node_photo -->|"analyzes image"| node_vision
node_photo -->|"replies with description"| node_telegram
node_bridge_app -->|"reacts to messages"| node_reactions
node_reactions -->|"sends reactions"| node_telegram
node_reply -->|"adds buttons"| node_feedback
node_feedback -->|"delivers buttons"| node_telegram
node_feedback -->|"sends reports"| node_admin
node_bridge_app -->|"serves SSE"| node_mcp_endpoint
node_claude -->|"connects over SSE"| node_mcp_endpoint
node_telegram -.->|"webhook updates"| node_worker_webhook
node_worker_webhook -.->|"forwards when online"| node_bridge_app
node_worker_webhook -.->|"uses when offline"| node_worker_fallback
node_worker_fallback -.->|"requests answer"| node_gemini

click node_bridge_app "https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js"
click node_allowlist "https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js"
click node_reply "https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js"
click node_context "https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js"
click node_history "https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js"
click node_photo "https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js"
click node_reactions "https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js"
click node_feedback "https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js"
click node_mcp_endpoint "https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js"
click node_worker_webhook "https://github.com/moeinv363/telegram-mcp-bridge/blob/main/telegram-worker/src/worker.js"
click node_worker_fallback "https://github.com/moeinv363/telegram-mcp-bridge/blob/main/telegram-worker/src/worker.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bridge_app,node_allowlist,node_reply,node_context,node_history,node_history_store,node_photo,node_reactions,node_feedback,node_user toneBlue
class node_mcp_endpoint toneAmber
class node_worker_webhook,node_worker_fallback,node_telegram toneMint
class node_admin,node_llm,node_vision,node_claude,node_gemini toneIndigo
```

## Components

### Local Telegram Bridge

- [Bridge runtime](https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js): `server.js`
- [Allowlist](https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js): `server.js`
- [Instant replies](https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js): `server.js`
- [Per-chat context](https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js): `server.js`
- [History persistence](https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js): `server.js`
- **History file**
- [Photo vision](https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js): `server.js`
- [Emoji reactions](https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js): `server.js`
- [Feedback buttons](https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js): `server.js`

### Claude Integration

- [MCP SSE endpoint](https://github.com/moeinv363/telegram-mcp-bridge/blob/main/server.js): `server.js`

### Worker Fallback

- [Telegram webhook](https://github.com/moeinv363/telegram-mcp-bridge/blob/main/telegram-worker/src/worker.js): `telegram-worker/src/worker.js`
- [Gemini fallback](https://github.com/moeinv363/telegram-mcp-bridge/blob/main/telegram-worker/src/worker.js): `telegram-worker/src/worker.js`

### Other components

- **Telegram user**
- **Telegram Bot API**
- **Bot admin**
- **OpenAI-compatible LLM**
- **Vision model**
- **Claude Code**
- **Gemini**

## Connections

- Telegram user → Telegram Bot API: messages (evidence: `README.md`)
- Telegram Bot API → Bridge runtime: delivers updates (evidence: `README.md`)
- Bridge runtime → Allowlist: restricts users (evidence: `README.md`)
- Bridge runtime → Instant replies: auto-replies (evidence: `README.md`)
- Instant replies → OpenAI-compatible LLM: requests answer (evidence: `README.md`)
- Bridge runtime → Per-chat context: keeps chat context (evidence: `README.md`)
- Per-chat context → History persistence: persists conversations (evidence: `README.md`)
- History persistence → History file: reads and writes (evidence: `README.md`)
- Telegram Bot API → Photo vision: sends photos (evidence: `README.md`)
- Photo vision → Vision model: analyzes image (evidence: `README.md`)
- Photo vision → Telegram Bot API: replies with description (evidence: `README.md`)
- Bridge runtime → Emoji reactions: reacts to messages (evidence: `README.md`)
- Emoji reactions → Telegram Bot API: sends reactions (evidence: `README.md`)
- Instant replies → Feedback buttons: adds buttons (evidence: `README.md`)
- Feedback buttons → Telegram Bot API: delivers buttons (evidence: `README.md`)
- Feedback buttons → Bot admin: sends reports (evidence: `README.md`)
- Bridge runtime → MCP SSE endpoint: serves SSE (evidence: `README.md`)
- Claude Code → MCP SSE endpoint: connects over SSE (evidence: `README.md`)
- Telegram Bot API → Telegram webhook: webhook updates (evidence: `README.md`)
- Telegram webhook → Bridge runtime: forwards when online (evidence: `README.md`)
- Telegram webhook → Gemini fallback: uses when offline (evidence: `README.md`)
- Gemini fallback → Gemini: requests answer (evidence: `README.md`)
