Telegram MCP

What chigwell/telegram-mcp MCP server does

The chigwell/telegram-mcp MCP server connects MCP-compatible clients to a Telegram account through Telethon. Its toolset covers account information, chats, groups, channels, messages, contacts, media, folders, drafts, profile settings, privacy controls, bot commands, and message events.

The server is suited to workflows that need an agent to inspect conversation history, find or send messages, manage chat membership and permissions, handle files or voice notes, or read Telegram account data. It supports clients such as Claude and Cursor, as well as other clients that implement MCP.

How it works

Telegram operations are exposed as MCP tools. Calls can be routed to configured accounts by account label. Message tools support sending, scheduling, editing, deleting, forwarding, pinning, replying, searching, reading context, managing reactions, creating polls, and handling inline buttons and callbacks.

The chigwell/telegram-mcp MCP server also provides waiting tools for incoming messages. wait_for_new_message and wait_for_settled_message can monitor one chat when chat_id is supplied; without that filter, an unrelated conversation can wake the wait. An opt-in callback-style event feed is available for Claude Code.

Contact aliases let users map several remembered names to one contact. Exact saved wording can resolve directly, while uncertain or ambiguous references return instructions for confirmation rather than sending a message. Alias data is stored locally in a JSON file.

Setup and configuration

The README identifies Telethon as the Telegram client library and describes support for Docker, multiple accounts, device identity, proxy settings, and MCP client configuration. The supplied material does not include the actual startup command or the Telegram credential variables, so those details should be taken from the repository’s setup instructions before deployment.

Optional behavior can be configured with environment variables. TELEGRAM_CONTACT_FUZZY=0 disables contact-name suggestions. TELEGRAM_ALIASES_FILE changes the alias file location. Transcription behavior is controlled with TELEGRAM_TRANSCRIBE, TELEGRAM_TRANSCRIBE_ENGINE, TELEGRAM_TRANSCRIBE_MAX_VOICES, TELEGRAM_TRANSCRIBE_MAX_SECONDS, and TELEGRAM_TRANSCRIPT_CACHE_DIR.

Tools and capabilities

The chigwell/telegram-mcp MCP server includes more than 80 tools grouped around:

• Account listing and account-specific routing
• Chat, group, channel, membership, invitation, admin, ban, permission, topic, and invite-link operations
• Message creation, retrieval, search, scheduling, editing, deletion, forwarding, reactions, polls, read status, and replies
• Contact discovery and management, including aliases
• File, media, voice-note, sticker, GIF, upload, download, and media inspection operations
• Voice transcription through Groq or Telegram Premium transcription
• Profile, privacy, user, photo, and bot-command management
• Folder and draft management
• Incoming-message waits and event delivery

Voice transcription uses Groq by default and requires GROQ_API_KEY when that engine is selected. Telegram-native transcription requires Telegram Premium. Transcripts are cached in a local SQLite store and are marked as machine-generated text rather than verbatim quotations.

Limitations and notes

Rich Markdown and HTML formatting modes require Telegram Premium. If Premium is unavailable, the relevant message operation sends nothing and returns a structured result indicating that classic formatting should be used instead.

Groq transcription uploads recordings outside Telegram and has a configurable size limit, which defaults to 25 MB. Telegram-native transcription stays within Telegram but may omit the final speech segment and can return a pending result for longer recordings. Cached transcripts may appear in message listings depending on the TELEGRAM_TRANSCRIBE setting.

Alias matching is intentionally conservative. Unknown, ambiguous, stale, or merely similar references do not send messages automatically; the agent must obtain confirmation and save the confirmed wording before retrying. Alias and transcript files contain personal data and should be protected with appropriate filesystem permissions.