Telegram

A Telegram integration for Claude, Cursor, and other MCP-compatible clients. It exposes Telegram account, chat, message, contact, media, folder, and admin operations through the Model Context Protocol using Telethon.

🤖 MCP in Action

Basic Telegram MCP usage in Claude:

Asking Claude to analyze chat history and send a response:

Message sent successfully:

Contents

• Skills & Practical Workflows
• What It Can Do
• Requirements
• Quick Start
• MCP Client Configuration
• Multi-Account Setup
• Device Identity
• Expected Account Check
• Proxy Support
• File Path Security
• Chat Access Privacy (Allowlist)
• Docker
• Development
• Security Notes
• Troubleshooting
• License

Skills & Workflows

Looking for ready-to-use workflows, prompt examples, or integration recipes? Explore the Skills Documentation for step-by-step guides on:

• Summarizing unread messages safely
• Drafting replies without sending
• Triaging action items & urgent requests
• Searching chat history and expanding context

What It Can Do

The server currently includes 80+ MCP tools grouped into these areas:

• Accounts: list configured accounts and route tool calls by account label.
• Chats and groups: list chats, inspect metadata, create groups/channels, join or leave chats, invite or remove users, manage admins, bans, default permissions, slow mode, topics, invite links, common chats, read receipts, and message links.
• Messages: send, schedule, edit, delete, forward, pin, unpin, mark read, reply, search, inspect context, create polls, manage reactions, inspect inline buttons, and press inline callbacks. send_message, reply_to_message, and edit_message support classic formatting (parse_mode='md'/'html') and server-side rich formatting (parse_mode='rich'/'rich_markdown'/'rich_html' — full Markdown/HTML with tables, headings, formulas, and collapsible sections). Rich modes require Telegram Premium on the account; Premium is re-checked on every call, and without it nothing is sent — the tool returns a structured telegram_premium_required result so the agent can reformat with classic modes and retry. send_message, reply_to_message, and edit_message also accept format_date to render a date as a tappable chip.

get_message_reactions returns an empty list for a message with no reactions. To reuse a custom reaction, pass the returned custom:<document_id> value to send_reaction.

• Contacts: list, search, add, delete, block, unblock, import, export, inspect direct chats, find recent contact interactions, and remember contacts by the names you actually use (see below).

Remembered contacts

set_contact_alias teaches the server what you call someone, and every tool that takes a chat_id understands it from then on — send_message("андрей бекендер", ...) just works. A contact can carry any number of aliases, which is how tags work: save both андрей бекендер and бекендер for the same person and either resolves.

Only an exact saved wording ever sends. Similar wording (Андрею бекендеру for a saved андрей бекендер) is matched too, but only to suggest: the tool sends nothing and asks you to confirm the contact by name. This is deliberate — Лена/Леня and Иван/Иванов differ exactly as much as a case ending does, so a matcher confident enough to handle declensions is also confident enough to message the wrong person whenever the one you meant is not saved yet. Confirming saves that wording as its own alias, so each new phrasing costs one yes/no the first time and nothing ever again. Set TELEGRAM_CONTACT_FUZZY=0 to drop the suggestions too.

When a reference is unknown, resembles one contact, matches several, or points at a contact that no longer resolves, tools send nothing and return a structured instruction telling the agent exactly what to ask you, to save the answer with set_contact_alias, and to retry once. list_contact_aliases shows one row per person with all their aliases (use it to spot a wrong memory), delete_contact_alias forgets one, and repointing an alias at someone else requires replace=True. The save path itself refuses a target it would have to guess at: contacts are saved by @username, phone, numeric ID, or an alias already confirmed for them.

Aliases live in ${XDG_STATE_HOME:-~/.local/state}/telegram-mcp/aliases.json (owner-only, written atomically); TELEGRAM_ALIASES_FILE overrides the path, and a pre-existing aliases.json next to the code is still read as a fallback.

• Media: send files, download media, upload files, send voice notes, stickers, GIFs, inspect message media, and transcribe voice messages/video notes (see below).

Voice transcription

transcribe_voice(chat_id, message_id, engine=None) turns a voice message or video note into text. Four engines are available:

• groq (default): uploads the recording to Groq's hosted whisper-large-v3-turbo. Leaves the server and costs a download+upload per call, but doesn't drop the recording's last few words the way native transcription does. Requires GROQ_API_KEY. Groq caps the size of a single upload, so a recording above TELEGRAM_TRANSCRIBE_GROQ_MAX_MB (default 25, the free-tier limit) is refused locally with a too_large error naming its size instead of being downloaded and rejected by the API. Raise the limit if your Groq tier allows bigger files, or transcribe that message with engine='telegram', which has no such cap.
• telegram: native Telegram Premium transcription (messages.TranscribeAudioRequest). Free and never leaves Telegram, but empirically drops the last speech segment in roughly 2 of 3 recordings and requires Telegram Premium on the account. Long recordings come back pending and are polled automatically.
• openai: any OpenAI-compatible /audio/transcriptions endpoint — OpenAI itself, a self-hosted Parakeet or speaches server, LocalAI, a vLLM Whisper deployment, and so on. Set TELEGRAM_TRANSCRIBE_OPENAI_URL to the API base URL (e.g. https://api.openai.com/v1; a full .../audio/transcriptions URL also works), TELEGRAM_TRANSCRIBE_OPENAI_API_KEY for the bearer token (optional for keyless local servers), and TELEGRAM_TRANSCRIBE_OPENAI_MODEL (default whisper-1). Size cap: TELEGRAM_TRANSCRIBE_OPENAI_MAX_MB (default 25). For Parakeet use TELEGRAM_TRANSCRIBE_OPENAI_URL=http://localhost:5092/v1, the API key only if the server sets PARAKEET_API_KEY, and set TELEGRAM_TRANSCRIBE_LANGUAGE for anything that isn't English — Parakeet assumes en when no language is sent.
• whisper: a local faster-whisper model loaded inside the MCP server process. The audio never leaves the machine. Install the extra with pip install 'telegram-mcp[whisper]' (or uv sync --extra whisper). TELEGRAM_TRANSCRIBE_WHISPER_MODEL picks the model (default small; e.g. large-v3-turbo for better quality), TELEGRAM_TRANSCRIBE_WHISPER_DEVICE (auto/cpu/cuda), TELEGRAM_TRANSCRIBE_WHISPER_COMPUTE_TYPE (e.g. int8 on CPU) and TELEGRAM_TRANSCRIBE_WHISPER_MODEL_DIR (where models are downloaded) tune it. The model is loaded once on first use and recordings are transcribed one at a time. Not available in the Alpine Docker image; use openai against a Parakeet or other OpenAI-compatible server next to the container instead.

TELEGRAM_TRANSCRIBE_LANGUAGE (ISO-639-1, e.g. nl) is passed as a language hint to every engine except telegram; unset, the engines auto-detect. TELEGRAM_TRANSCRIBE_TIMEOUT (default 120 seconds) bounds a single request to the HTTP engines (groq, openai).