fast-mcp-telegram

What is fast-mcp-telegram?

fast-mcp-telegram is an MCP (Model Context Protocol) server that transforms an AI assistant into a Telegram power user. It provides full Telegram API access—including message search, sending/editing messages, contact management, phone number integration, and direct MTProto calls—for any MCP-compatible client (e.g., Cursor, Claude Desktop).

How to use fast-mcp-telegram?

Install via uvx (recommended), local git clone, or Docker. For each method, first set API_ID, API_HASH, and PHONE_NUMBER as environment variables and run a one‑time authentication setup to create a Telegram session file. Then configure your MCP client with the appropriate command or URL, and start invoking tools like search_messages, send_or_edit_message, or search_contacts.

Key features of fast-mcp-telegram

• Smart global and per‑chat message search with date/type filters
• Send, edit, and reply to messages with Markdown/HTML formatting
• Search contacts by name, username, or phone number
• Message users directly by phone number with auto‑contact management
• Direct MTProto access for advanced low‑level operations
• Async operations, connection pooling, and auto‑reconnect for reliability
• Docker deployment with HTTP transport and optional Traefik reverse proxy

Use cases of fast-mcp-telegram

• Let an AI assistant search all Telegram messages for deadlines or keywords.
• Automatically send reminders or replies to saved messages or specific chats.
• Retrieve user profiles and contact details for verification or lookup.
• Read specific messages by ID for auditing or summarization.
• Build a production Telegram bot running behind a reverse proxy.

FAQ from fast-mcp-telegram

What prerequisites are needed?

Python 3.10+, Telegram API credentials (from my.telegram.org), and an MCP-compatible client.

How is the Telegram session stored and authenticated?

A one‑time setup script creates an authenticated session file. For uvx/local it is saved to ~/.config/fast-mcp-telegram/mcp_telegram.session or the project directory; for Docker it is written to ./mcp_telegram.session.

Can fast-mcp-telegram run over HTTP instead of stdio?

Yes. When using Docker deployment, set MCP_TRANSPORT=http and expose the service via a domain. The client can then connect via HTTP POST or a url configuration.

What chat formats are supported for chat_id?

Supported formats: 'me' (Saved Messages), @username, numeric user ID, and channel IDs like -1001234567890.

Are there any known limits or security considerations?

The README mentions a “Security Considerations” section (details not provided in the excerpt) and advises production users to follow Docker deployment best practices. No explicit rate limits or data‑retention policies are stated.