fast-mcp-telegram

SSE

by leshchenko1979

360 downloads Not rated yet
GitHub Website SSE

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

Transport
SSE

Explore

| Feature | Description |
|---------|-------------|
| 🔍 Smart Search | Global & per-chat message search with filters |
| 💬 Messaging | Send, edit, reply with formatting support |
| 👥 Contacts | Search users, get profiles, manage contacts |
| 📱 Phone Integration | Message by phone number, auto-contact management |
| 🔧 Low-level API | Direct MTProto access for advanced operations |
| ⚡ Performance | Async operations, connection pooling, caching |
| 🛡️ Reliability | Auto-reconnect, structured logging, error handling |

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:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name fast-mcp-telegram
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

- Docker & Docker Compose installed
- Telegram API credentials (get them here)
- Domain name (for Traefik reverse proxy setup)

- Python 3.10+
- Telegram API credentials (get them here)
- MCP-compatible client (Cursor, Claude Desktop, etc.)

| Path | Best For | Complexity | Maintenance |
|------|----------|------------|-------------|
| 🚀 uvx (Recommended) | Most users, quick setup | ⭐⭐⭐⭐⭐ Easy | ✅ Auto-updates |
| 🐳 Docker (Production) | Production deployment | ⭐⭐⭐⭐ Easy | 🐳 Container updates |
| 💻 Local Installation | Developers, contributors | ⭐⭐⭐ Medium | 🔧 Manual updates |

Choose your path below:
- uvx Path (2-minute setup)
- Local Installation Path
- 🐳 Docker Deployment (Production)

---

``bash
API_ID="your_api_id" API_HASH="your_api_hash" PHONE_NUMBER="+123456789" \
uvx --from git+https://github.com/leshchenko1979/fast-mcp-telegram.git@master fast-mcp-telegram-setup
json
{
"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"
}
}
}
}
bash
git clone https://github.com/leshchenko1979/fast-mcp-telegram.git
cd fast-mcp-telegram
uv sync # Install dependencies
json
{
"mcpServers": {
"telegram": {
"command": "python3",
"args": ["/path/to/fast-mcp-telegram/src/server.py"],
"cwd": "/path/to/fast-mcp-telegram"
}
}
}


Create a .env file in your project directory:
bash

MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8000
SESSION_NAME=mcp_telegram

DOMAIN=your-domain.com

Important: The setup process creates an authenticated Telegram session file at ./mcp_telegram.session in your project directory.



docker compose --profile setup run --rm setup


The default domain is your-domain.com. To use your own domain:



1. Set up DNS: Point your domain to your server

2. Configure environment: Add DOMAIN=your-domain.com to your .env file

3. Traefik network: Ensure traefik-public network exists on your host



Example:
bash


For production deployment on a remote server:
bash

export VDS_USER=your_server_user
export VDS_HOST=your.server.com
export VDS_PROJECT_PATH=/path/to/deployment

./scripts/deploy-mcp.sh
`

The script will:
- Transfer project files to your server
- Copy environment file
- Build and start the Docker containers

For HTTP-based MCP clients:

`json
{
"mcpServers": {
"telegram": {
"command": "curl",
"args": ["-X", "POST", "https://your-domain.com/mcp"],
"env": {}
}
}
}
`

Or for direct HTTP connection:

``json
{
"mcpServers": {
"telegram": {
"url": "https://your-domain.com"
}
}
}
bash

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

| Tool | Purpose | Key Features |
|------|---------|--------------|
| search_messages | Search messages globally or in specific chats | Filters by date, chat type, multiple queries |
| send_or_edit_message | Send new messages or edit existing ones | Markdown/HTML formatting, replies |
| read_messages | Read specific messages by ID | Bulk reading, full metadata |
| search_contacts | Find users and contacts | By name, username, or phone |
| get_contact_details | Get user/chat profile information | Bio, status, online state |
| send_message_to_phone | Message by phone number | Auto-contact management |
| invoke_mtproto | Direct Telegram API access | Advanced operations |

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"
        }
    }
}
Python Version License: MIT Docker Ready <div align="center">
No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

More like this

Similar MCP servers you might find useful

Browse category

Playwright

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

— 92.5k 401.1k dl
Automation

Slack

Slack MCP Server connects compatible AI clients with Slack workspaces, allowing models and agents to read channels and send messages through Model Context…

— 88.1k 401.1k dl
Communication

Fetch

Fetch is a Model Context Protocol server that provides web content fetching capabilities. It enables LLMs to retrieve and process content from web pages…

— 88.1k 954.3k dl
Automation