chigwell/telegram-mcp

Telegram MCP server powered by Telethon to let MCP clients read chats, manage groups, and send/modify messages, media, contacts, and settings.

Telegram MCP Server – What It Is

Telegram MCP is a self‑hosted Python server that lets AI agents (Claude, Cursor, or any client that speaks the Model Context Protocol – MCP) interact with a Telegram account as if it were a set of native tools. It translates MCP tool calls into Telethon‑based Telegram API actions, exposing everything you can do in Telegram – reading chats, sending messages, managing groups, handling contacts, media, folders, events, and even voice‑to‑text transcription.

Core Idea

MCP ↔ Telegram bridge – The server implements the open‑source Model Context Protocol, turning Telegram operations into structured JSON‑based tools that LLM‑driven agents can call.
Agent‑friendly – Results are sanitized JSON, and the server reports special error objects (e.g., telegram_premium_required) so the agent can adapt its behaviour.

What You Can Do With It

Area	Example Capabilities
Accounts	List multiple configured accounts, route calls by label.
Chats & Groups	List chats, create/join/leave groups, manage admins, bans, slow‑mode, topics, invite links, read receipts, etc.
Messages	Send, edit, delete, forward, schedule, pin, react, create polls, reply, search, retrieve context, and use rich formatting (Markdown/HTML with tables, formulas, collapsible sections) – premium‑only.
Contacts	List, search, add, block, import/export, and remember aliases (e.g., `send_message("андрей бекендер", …)` works after you teach the alias).
Media	Upload/download files, stickers, GIFs, voice notes, and transcribe voice/video using one of four engines (Groq Whisper, Telegram Premium, OpenAI‑compatible, or local Faster‑Whisper).
Profile & Privacy	Get/set profile info, photos, privacy settings, bot commands.
Folders & Drafts	List, create, reorder, delete folders; save, list, clear drafts; snapshot folder definitions for backup/restore.
Events	Wait for new messages (`wait_for_new_message`), or enable a callback‑style incoming feed that writes JSON lines to a file for agents that can monitor a file (e.g., Claude Code).
Custom Emoji & Tappable Dates	Retrieve custom emoji IDs and reuse them via `<tg-emoji>` tags; embed tappable date chips with `format_date`.

Voice Transcription Details

Groq – Hosted Whisper‑large‑v3‑turbo, requires GROQ_API_KEY. Caps uploads at 25 MiB by default.
Telegram – Uses Telegram Premium’s native transcription (free, stays on Telegram) but may drop the last segment.
OpenAI – Any /audio/transcriptions endpoint (OpenAI, Parakeet, LocalAI, etc.).
Whisper – Local Faster‑Whisper model (pip install 'telegram-mcp[whisper]').

Transcripts are cached in a SQLite file; repeated requests hit the cache, and concurrent identical requests are coalesced.

Getting Started (Quick‑Start)

Clone & install – git clone https://github.com/chigwell/telegram-mcp.git && uv sync (requires Python 3.10+).
Create a session string – uv run session_string_generator.py (QR code or phone‑number flow).
Configure – Copy .env.example to .env and fill in TELEGRAM_API_ID, TELEGRAM_API_HASH, and TELEGRAM_SESSION_STRING.
Run – uv run telegram-mcp (or via Docker – see below).
Optional – Migrate to a persistent SQLite session (uv run telegram-mcp-migrate-session) for long‑running servers.

Deployment Options

Docker – Official images build automatically; mount a volume for data/transcripts (the transcript cache) and for the state directory (~/.local/state/telegram-mcp).
Multi‑account – Define multiple accounts in the .env (e.g., ACCOUNT_1_LABEL, ACCOUNT_2_LABEL) and route calls by the account argument.
Proxy support – Set TELEGRAM_PROXY to a SOCKS/HTTP proxy URL.
Security – Files storing aliases, session data, and incoming‑feed logs are created with owner‑only permissions (600/700). The README warns not to install the similarly‑named PyPI package telegram-mcp as it is unrelated.

Who Might Use This?

LLM‑powered personal assistants that need to read or act on Telegram messages (e.g., Claude Code, Cursor, custom MCP hosts).
Automation engineers building bots that operate across multiple Telegram accounts while keeping the logic in an LLM rather than hard‑coded scripts.
Researchers exploring how LLMs can safely interact with real‑world messaging platforms, thanks to the explicit error objects and privacy‑focused design (allow‑list chat access, alias confirmation, etc.).

License & Community

License: Apache 2.0 – permissive for commercial and research use.
Status: Actively maintained (GitHub Actions for linting, Docker builds, and CI). Contributions are welcomed via pull requests.

TL;DR

Telegram MCP Server is a Python bridge that turns Telegram into a rich set of MCP‑compatible tools, enabling LLM agents to read, write, manage, and transcribe Telegram content programmatically, with support for multiple accounts, rich formatting, custom emoji, and secure, cache‑aware voice transcription.