fast-mcp-telegram
@leshchenko1979
About fast-mcp-telegram
AI-powered Telegram automation via MCP protocol. Search messages, send automated replies, manage contacts - enable your AI assistant with full Telegram API access through FastMCP.
Basic information
Config
Add this server to your MCP-compatible client using the configuration below.
{
"mcpServers": {
"telegram": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/leshchenko1979/fast-mcp-telegram.git@master",
"fast-mcp-telegram"
],
"env": {
"API_ID": "your_api_id",
"API_HASH": "your_api_hash",
"PHONE_NUMBER": "+123456789"
}
}
}
}Tools
9Search messages across all Telegram chats (global search). FEATURES: - Multiple queries: "term1, term2, term3" - Date filtering: ISO format (min_date="2024-01-01") - Chat type filter: "private", "group", "channel" SEARCH LIMITATIONS: - NO wildcards: "proj*", "meet%" won't work - NO regex: "^project", "deadline$" won't work - Use simple terms: "proj" finds "project", "projects" - Case insensitive: "DEADLINE" finds "deadline" EXAMPLES: search_messages_globally(query="deadline", limit=20) # Global search search_messages_globally(query="project, launch", limit=30) # Multi-term search search_messages_globally(query="proj", limit=20) # Partial word search Args: query: Search terms (required). Comma-separated for multiple terms. limit: Max results (default: 50) min_date: Min date in YYYY-MM-DD format max_date: Max date in YYYY-MM-DD format chat_type: Filter by "private", "group", or "channel" auto_expand_batches: Extra batches for filtered results include_total_count: Include total count (ignored in global mode)
Search messages within a specific Telegram chat. FEATURES: - Multiple queries: "term1, term2, term3" - Date filtering: ISO format (min_date="2024-01-01") - Total count support for per-chat searches SEARCH LIMITATIONS: - NO wildcards: "proj*", "meet%" won't work - NO regex: "^project", "deadline$" won't work - Use simple terms: "proj" finds "project", "projects" - Case insensitive: "DEADLINE" finds "deadline" EXAMPLES: search_messages_in_chat(chat_id="me", limit=10) # Latest messages (no query) search_messages_in_chat(chat_id="-1001234567890", query="launch") # Specific chat search_messages_in_chat(chat_id="telegram", query="update, news") # Multi-term search search_messages_in_chat(chat_id="me", query="proj") # Partial word search Args: chat_id: Target chat ('me', ID, username, or -100... channel ID) query: Optional search term(s). If omitted, returns latest messages. limit: Max results min_date: Min date (YYYY-MM-DD) max_date: Max date (YYYY-MM-DD) auto_expand_batches: Extra batches for filtered results include_total_count: Include total matching count
Send new message in Telegram chat. FORMATTING: - parse_mode=None: Plain text - parse_mode="markdown": *bold*, _italic_, [link](url), `code` - parse_mode="html": <b>bold</b>, <i>italic</i>, <a href="url">link</a>, <code>code</code> EXAMPLES: send_message(chat_id="me", message="Hello!") # Send to Saved Messages send_message(chat_id="-1001234567890", message="New message", reply_to_msg_id=12345) # Reply to message Args: chat_id: Target chat ID ('me' for Saved Messages, numeric ID, or username) message: Message text to send reply_to_msg_id: Reply to specific message ID (optional) parse_mode: Text formatting ("markdown", "html", or None)
Edit existing message in Telegram chat. FORMATTING: - parse_mode=None: Plain text - parse_mode="markdown": *bold*, _italic_, [link](url), `code` - parse_mode="html": <b>bold</b>, <i>italic</i>, <a href="url">link</a>, <code>code</code> EXAMPLES: edit_message(chat_id="me", message_id=12345, message="Updated text") # Edit Saved Messages edit_message(chat_id="-1001234567890", message_id=67890, message="*Updated* message") # Edit with formatting Args: chat_id: Target chat ID ('me' for Saved Messages, numeric ID, or username) message_id: Message ID to edit (required) message: New message text parse_mode: Text formatting ("markdown", "html", or None)
Read specific messages by their IDs from a Telegram chat. SUPPORTED CHAT FORMATS: - 'me': Saved Messages - Numeric ID: User/chat ID (e.g., 133526395) - Username: @channel_name or @username - Channel ID: -100xxxxxxxxx USAGE: - First use search_messages() to find message IDs - Then read specific messages using those IDs - Returns full message content with metadata EXAMPLES: read_messages(chat_id="me", message_ids=[680204, 680205]) # Saved Messages read_messages(chat_id="-1001234567890", message_ids=[123, 124]) # Channel Args: chat_id: Target chat identifier (use 'me' for Saved Messages) message_ids: List of message IDs to retrieve (from search results)
Search Telegram contacts and users by name, username, or phone number. SEARCH SCOPE: - Your saved contacts - Global Telegram users - Public channels and groups QUERY TYPES: - Name: "John Doe" or "Иванов" - Username: "@username" (without @) - Phone: "+1234567890" WORKFLOW: 1. Search for contact: search_contacts("John Doe") 2. Get chat_id from results 3. Search messages: search_messages(chat_id=chat_id, query="topic") EXAMPLES: search_contacts("@telegram") # Find user by username search_contacts("John Smith") # Find by name search_contacts("+1234567890") # Find by phone Args: query: Search term (name, username without @, or phone with +) limit: Max results (default: 20, recommended: ≤50)
Get detailed profile information for a specific Telegram user or chat. USE CASES: - Get full user profile after finding chat_id - Retrieve contact details, bio, and status - Check if user is online/bot/channel SUPPORTED FORMATS: - Numeric user ID: 133526395 - Username: "telegram" (without @) - Channel ID: -100xxxxxxxxx EXAMPLES: get_contact_details("133526395") # User by ID get_contact_details("telegram") # User by username get_contact_details("-1001234567890") # Channel by ID Args: chat_id: Target chat/user identifier (numeric ID, username, or channel ID)
Send message to phone number, auto-managing Telegram contacts. FEATURES: - Auto-creates contact if phone not in contacts - Sends message immediately after contact creation - Optional contact cleanup after sending - Full message formatting support CONTACT MANAGEMENT: - Checks existing contacts first - Creates temporary contact only if needed - Removes temporary contact if remove_if_new=True REQUIREMENTS: - Phone number must be registered on Telegram - Include country code: "+1234567890" EXAMPLES: send_message_to_phone("+1234567890", "Hello from Telegram!") # Basic send send_message_to_phone("+1234567890", "*Important*", remove_if_new=True) # Auto cleanup Args: phone_number: Target phone number with country code (e.g., "+1234567890") message: Message text to send first_name: Contact first name (for new contacts only) last_name: Contact last name (for new contacts only) remove_if_new: Remove contact after sending if newly created reply_to_msg_id: Reply to specific message ID parse_mode: Text formatting ("markdown", "html", or None) Returns: Message send result + contact management info (contact_was_new, contact_removed)
Execute low-level Telegram MTProto API methods directly. USE CASES: - Access advanced Telegram API features - Custom queries not covered by standard tools - Administrative operations METHOD FORMAT: - Full class name: "messages.GetHistory", "users.GetFullUser" - Telegram API method names with proper casing PARAMETERS: - JSON string with method parameters - Parameter names match Telegram API documentation - Supports complex nested objects EXAMPLES: invoke_mtproto("users.GetFullUser", '{"id": {"_": "inputUserSelf"}}') # Get self info invoke_mtproto("messages.GetHistory", '{"peer": {"_": "inputPeerChannel", "channel_id": 123456, "access_hash": 0}, "limit": 10}') Args: method_full_name: Telegram API method name (e.g., "messages.GetHistory") params_json: Method parameters as JSON string Returns: API response as dict, or error details if failed
Overview
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.
More Communication MCP servers
WhatsApp Web MCP
pnizerWhatsApp Web MCP Server
Discord Mcp
SaseQA MCP server for the Discord integration. Enable your AI assistants to seamlessly interact with Discord. Enhance your Discord experience with powerful automation capabilities.
MCP Email Server
Shy2593666979一个基于 MCP (Model Context Protocol) 的邮件服务，支持 LLM 发送带附件的电子邮件及在指定目录中搜索文件。提供安全的 SMTP 传输、多收件人支持和附件模式匹配搜索功能，适用于 Gmail、Outlook、Yahoo、QQ 邮箱和网易 126 邮箱等主流邮箱服务。
MCP-Discord
barryyip0625Implement Discord MCP server enabling AI assistants to interact with the Discord platform.
Teams Mcp
floriscornelMCP server providing comprehensive Microsoft Teams and Graph API access for AI assistants including messaging, search, and user management.
Comments