# sparfenyuk/mcp-telegram architecture

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

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

## Overview

##### Project Type and Purpose
- This is a single‐service Python application exposing a Model Context Protocol (MCP) server that bridges Telegram’s API and AI assistants (e.g., Claude Desktop).
- It is packaged as a CLI tool (cli.py) and run under the `uv` runtime (uv tool).

##### Main Components
a. External Client
- **Claude Desktop** (MCP client)
b. Runtime & Entry
- **uv Runtime** (the `uv` tool orchestrates the server process)
- **CLI Entrypoint** (`cli.py`)
c. Server Core
- **MCP Server** (`src/mcp_telegram/server.py`)
- **Tool Registry** (`src/mcp_telegram/tools.py`)
- **Tool Runners** (individual handlers registered via `tool_runner.register`)
d. Telegram Integration
- **Telegram API Wrapper** (`src/mcp_telegram/telegram.py`)
- **Environment Configuration** (env vars: `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`, phone number session)
- **Telegram Servers** (external HTTPS endpoints)
e. Supporting Files
- `pyproject.toml`, `cog.toml`, `.pre-commit-config.yaml`, etc., for build/config (these live at top level)

##### Out Interactions & Data Flow
- **Startup**: Claude Desktop → invokes `uv run mcp-telegram` → `uv` launches `cli.py`
- **Server Initialization**: `cli.py` loads server from `server.py`, reads env vars, connects to Telegram via wrapper.
- **MCP Protocol**: The server listens for MCP-formatted requests (JSON/STDIO or HTTP/WS depending on uv’s transport).
- **Tool Invocation**: On each request, the MCP Server dispatches to the appropriate tool in `tools.py`.
- The tool runner calls into methods in `telegram.py` (e.g., listing dialogs, fetching messages).
- **Telegram API Calls**: Telegram wrapper uses Telethon or HTTP endpoints, authenticates with provided API ID/HASH.
- **Response**: Results are packaged as MCP Response (TextContent, ImageContent, EmbeddedResource) and sent back to Claude.

##### Architectural Patterns & Design Principles
- **Separation of Concerns**:
- Entrypoint (`cli.py`) vs. Server logic (`server.py`)
- Tool definitions (`tools.py`) vs. API integration (`telegram.py`)
- **Plugin-style tool runners**: New tools can be added by subclassing `ToolArgs` and registering a runner.
- **Async I/O**: Entire stack is `async` to handle network I/O non-blocking.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Systems"
        direction TB
        Claude["Claude Desktop"]:::external
        TelegramCloud(("Telegram Servers")):::external
    end

    %% Runtime & Entry
    subgraph "Runtime & Entry"
        direction TB
        UV["uv Runtime"]:::entry
        CLI["cli.py"]:::entry
    end

    %% Server Core
    subgraph "Server Core"
        direction TB
        MCP["MCP Server Core"]:::internal
        Tools["Tool Registry"]:::internal
        Runners["Tool Runners"]:::internal
        Wrapper["Telegram API Wrapper"]:::internal
    end

    %% Environment
    Env["Environment Variables<br/>(TELEGRAM_API_ID, HASH, session)"]:::internal

    %% Supporting Files
    subgraph "Supporting Files"
        direction TB
        PYP["pyproject.toml"]:::config
        COG["cog.toml"]:::config
        PRE[".pre-commit-config.yaml"]:::config
        RUFF["ruff.toml"]:::config
        GIT[".gitignore"]:::config
        CHANGE["CHANGELOG.md"]:::config
        LICENSE["LICENSE"]:::config
        README["README.md"]:::config
    end

    %% Connections
    Claude -->|"uv run mcp-telegram"| UV
    UV -->|"exec"| CLI
    CLI -->|"initialize server"| MCP
    MCP -->|"dispatch request"| Tools
    Tools -->|"invoke runner"| Runners
    Runners -->|"calls API methods"| Wrapper
    Wrapper -->|"HTTPS/Telethon RPC"| TelegramCloud
    Env -->|"provides credentials"| Wrapper

    %% Click Events
    click UV "https://github.com/sparfenyuk/mcp-telegram/blob/main/uv.lock"
    click CLI "https://github.com/sparfenyuk/mcp-telegram/blob/main/cli.py"
    click MCP "https://github.com/sparfenyuk/mcp-telegram/blob/main/src/mcp_telegram/server.py"
    click Tools "https://github.com/sparfenyuk/mcp-telegram/blob/main/src/mcp_telegram/tools.py"
    click Wrapper "https://github.com/sparfenyuk/mcp-telegram/blob/main/src/mcp_telegram/telegram.py"
    click PYP "https://github.com/sparfenyuk/mcp-telegram/blob/main/pyproject.toml"
    click COG "https://github.com/sparfenyuk/mcp-telegram/blob/main/cog.toml"
    click PRE "https://github.com/sparfenyuk/mcp-telegram/blob/main/.pre-commit-config.yaml"
    click RUFF "https://github.com/sparfenyuk/mcp-telegram/blob/main/ruff.toml"
    click GIT "https://github.com/sparfenyuk/mcp-telegram/blob/main/.gitignore"
    click CHANGE "https://github.com/sparfenyuk/mcp-telegram/blob/main/CHANGELOG.md"
    click LICENSE "https://github.com/sparfenyuk/mcp-telegram/tree/main/LICENSE"
    click README "https://github.com/sparfenyuk/mcp-telegram/blob/main/README.md"

    %% Styles
    classDef entry fill:#FFA500,stroke:#333,stroke-width:1px
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:1px
```
