Telegram MCP

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.