How sparfenyuk/mcp-telegram works
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.