fast-mcp-telegram
About
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.
Details
- Author
- leshchenko1979
- Downloads
- 360
- Categories
- Communication, Automation
Jump to
- 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
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
fast-mcp-telegramCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
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.
search_messages_globally
Search 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_in_chat
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_message
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_message
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_messages
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_contacts
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_contact_details
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
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)
invoke_mtproto
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
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"fast-mcp-telegram": {
"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"
}
}
}
}
}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"
}
}
}Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
