fast-mcp-telegram

Name: fast-mcp-telegram
Author: leshchenko1979

@leshchenko1979

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.

#telegram #automation #ai-assistant

基本情報

カテゴリ

コミュニケーション

トランスポート

stdio

公開者

leshchenko1979

投稿者

Alexey Leshchenko

設定

以下の設定を使って、このサーバーを MCP 対応クライアントに追加してください。

{
  "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"
      }
    }
  }
}

ツール

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 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": bold, italic, <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": bold, italic, <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

概要

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.

「コミュニケーション」の他のコンテンツ

Mattermost MCP Server

pvev

Mattermost MCP server to enable Claude to interact with Mattermost Workspaces

MCP Communicator (Telegram)

qpd-v

An MCP server that enables communication with users through Telegram. This server provides a tool to ask questions to users and receive their responses via a Telegram bot.