fast-mcp-telegram 0.14.0

MCP server with Telegram search and messaging capabilities

Fast MCP Telegram Server - Production-ready Telegram integration for AI assistants with comprehensive search, messaging, and direct API access capabilities.

🌐 Demo

1. Open https://tg-mcp.l1979.ru/setup to begin the authentication flow.
2. After finishing, you'll receive a ready-to-use mcp.json with your Bearer token.
3. Use the config with your MCP client to check out this MCP server capabilities.
4. Or try the HTTP‑MTProto Bridge right away with curl (replace TOKEN):

curl -X POST "https://tg-mcp.l1979.ru/mtproto-api/messages.SendMessage" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params": {"peer": "me", "message": "Hello from Demo!"}}'

📖 Table of Contents

• ✨ Features
• 🎯 Design Philosophy
• 🚀 Quick Start
• 🏗️ Server Modes
• 🌐 HTTP-MTProto Bridge
• 📚 Documentation
• 🔒 Security
• 🤝 Contributing
• 📄 License

✨ Features

Feature	Description
🔐 Multi-User Authentication	Production-ready Bearer token auth with session isolation and LRU cache management
🌐 HTTP-MTProto Bridge	Direct curl access to any Telegram API method with entity resolution and safety guardrails
🔍 Unified Message API	Single get_messages tool for search, browse, read by IDs, and replies - 5 modes in one
💬 Universal Replies	Get replies from channel posts, forum topics, or any message with one parameter
🔎 Intelligent Search	Global & per-chat message search with multi-query support and intelligent deduplication
🏗️ Dual Transport	Seamless development (stdio) and production (HTTP) deployment support
📁 Secure File Handling	Rich media sharing with SSRF protection, size limits, album support, optional HTTP attachment streaming when DOMAIN is set to a real host
✉️ Advanced Messaging	Send, edit, reply, post to forum topics, formatting, file attachments, and phone number messaging
🎤 Voice Transcription	Automatic speech-to-text for Premium accounts with parallel processing and polling
📊 Unified Session Management	Single configuration system for setup and server, with multi-account support
👥 Smart Contact Discovery	Search users, groups, channels with uniform entity schemas, forum detection, profile enrichment
⚡ High Performance	Async operations, parallel queries, connection pooling, and memory optimization
🛡️ Production Reliability	Auto-reconnect, structured logging, comprehensive error handling with clear actionable messages
🎯 AI-Optimized	Literal parameter constraints, LLM-friendly API design, and MCP ToolAnnotations
🌍 Web Setup Interface	Browser-based authentication flow with immediate config generation

🎯 Design Philosophy

Save context space for LLMs by making tools as general-purpose as possible. Fewer, more capable tools consume less of the AI's context window than many narrow-purpose tools. We consolidate functionality (e.g. get_messages handles search, browse, read-by-ID, and replies in one tool; invoke_mtproto provides raw API access for edge cases), use uniform schemas across tools so responses can be automatically processed when possible, and keep descriptions concise. We accept more parameters per tool and slightly more complex signatures in exchange for fewer tools and less context. When adding capabilities, we prefer extending existing tools over introducing new ones.

🛠️ Available Tools

Tool	Purpose	Key Features
search_messages_globally	Search across all chats	Multi-term queries, date filtering, chat type filtering
get_messages	Unified message retrieval	Search/browse, read by IDs, get replies (posts/topics/messages), 5 modes
send_message	Send new message	File attachments (URLs/local), formatting (markdown/html), unified reply_to_id (message, forum topic, or channel post comment)
edit_message	Edit existing message	Text formatting, preserves message structure
find_chats	Find users/groups/channels	Multi-term search, contact discovery, username/phone lookup
get_chat_info	Get detailed profile info	Member counts, bio/about, online status, forum topics, enriched data
send_message_to_phone	Message phone numbers	Auto-contact management, optional cleanup, file support
invoke_mtproto	Direct Telegram API access	Raw MTProto methods, entity resolution, safety guardrails

📖 For detailed tool documentation with examples, see Tools Reference

🚀 Quick Start

1. Install from PyPI

pip install fast-mcp-telegram

2. Authenticate with Telegram

fast-mcp-telegram-setup --api-id="your_api_id" --api-hash="your_api_hash" --phone-number="[phone]"

🌐 Prefer a browser? Run the server and open /setup to authenticate and download a ready‑to‑use mcp.json. You can also reauthorize existing sessions through the same interface.

3. Configure Your MCP Client

STDIO Mode (Development with Cursor IDE):

{
  "mcpServers": {
    "telegram": {
      "command": "fast-mcp-telegram",
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash",
        "PHONE_NUMBER": "[phone]"
      }
    }
  }
}

HTTP_AUTH Mode (Production with Bearer Token):

{
  "mcpServers": {
    "telegram": {
      "url": "https://your-server.com",
      "headers": {
        "Authorization": "Bearer AbCdEfGh123456789KLmnOpQr..."
      }
    }
  }
}

4. Start Using!

// Global search across all chats
{"tool": "search_messages_globally", "params": {"query": "hello", "limit": 5}}

// Get latest messages from a chat
{"tool": "get_messages", "params": {"chat_id": "me", "limit": 10}}

// Search within a specific chat
{"tool": "get_messages", "params": {"chat_id": "@username", "query": "project"}}

// Read specific messages by ID
{"tool": "get_messages", "params": {"chat_id": "me", "message_ids": [123, 124]}}

// Get replies (channel posts, forum topics, or message replies)
{"tool": "get_messages", "params": {"chat_id": "-1001234567890", "reply_to_id": 42}}

// Send a message
{"tool": "send_message", "params": {"chat_id": "me", "message": "Hello from AI!"}}

📝 For detailed installation instructions, see Installation Guide

🏗️ Server Modes

Mode	Transport	Authentication	Use Case
STDIO	stdio	Disabled	Development with Cursor IDE
HTTP_NO_AUTH	HTTP	Disabled	Development HTTP server
HTTP_AUTH	HTTP	Required (Bearer token)	Production deployment

HTTP_AUTH Authentication Options

Header-Based Auth (Recommended):

{
  "mcpServers": {
    "telegram": {
      "url": "https://your-server.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer AbCdEfGh123456789..."
      }
    }
  }
}

URL-Based Auth (For Limited Clients):

{
  "mcpServers": {
    "telegram": {
      "url": "https://your-server.com/v1/url_auth/AbCdEfGh123456789.../mcp"
    }
  }
}

Auth Method	Security	Use When
Header-based	Higher (token not in logs)	Standard MCP clients (Cursor, Claude Code)
URL-based	Lower (token in logs)	Clients that cannot set custom headers

🌐 HTTP-MTProto Bridge

Direct curl access to any Telegram API method - Execute any Telegram MTProto method via HTTP requests with automatic entity resolution and safety guardrails.

Quick Examples

# Send message with automatic entity resolution
curl -X POST "https://your-domain.com/mtproto-api/messages.SendMessage" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params": {"peer": "@username", "message": "Hello from curl!"}}'

# Send message using params_json (works with n8n and other tools)
curl -X POST "https://your-domain.com/mtproto-api/messages.SendMessage" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params_json": "{\"peer\": \"@username\", \"message\": \"Hello from curl!\"}"}'

# Get message history with peer resolution
curl -X POST "https://your-domain.com/mtproto-api/messages.getHistory" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params": {"peer": "me", "limit": 10}}'

📖 For complete MTProto Bridge documentation, see MTProto Bridge Guide

📎 Attachment download URLs (HTTP)

When the server uses HTTP (not stdio) and DOMAIN is set to your real public host (same value as for /setup and MCP config — not the placeholder your-domain.com), message results from get_messages / search can include media.attachment_download_url for photos and file documents (not voice notes or round videos). The link base is derived from DOMAIN: hostname-only values get https:// (or http:// for localhost / 127.0.0.1); you can also set a full URL such as https://tg-mcp.example.com.

• GET /v1/attachments/{uuid} streams the file. No Authorization header is required; the random UUID is the capability until expiry.
• Configure ATTACHMENT_TICKET_TTL_SECONDS (default 3600) for ticket lifetime. Tickets live in process memory only — a restart drops them; use one replica unless you add external state later.
• Do not share these URLs in untrusted channels; anyone with the link can download while the ticket is valid. See SECURITY.md.

Example:

curl -sS -o file.pdf "https://tg-mcp.example.com/v1/attachments/<uuid-from-tool-response>"

📚 Documentation

• Installation Guide - Detailed installation and configuration
• Deployment Guide - Docker deployment and production setup
• Tools Reference - Complete tools documentation with examples
• Search Guidelines - Search best practices and limitations
• Operations Guide - Health monitoring and troubleshooting
• Project Structure - Code organization and architecture
• Contributing Guide - Development setup and contribution guidelines

🔒 Security

Key Security Features:

• Bearer token authentication with session isolation
• SSRF protection for file downloads
• Dangerous method blocking with opt-in override
• Session file security and automatic cleanup

📖 For complete security information, see SECURITY.md

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for:

• Development setup instructions
• Testing guidelines
• Code quality standards
• Pull request process

Quick Start for Contributors:

1. Fork the repository
2. Read the Contributing Guide
3. Create a feature branch
4. Make your changes and add tests
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FastMCP - MCP server framework
• Telethon - Telegram API library
• Model Context Protocol - Protocol specification

---

Made with ❤️ for the AI automation community

⭐ Star us on GitHub • 💬 English community • 💬 Russian community

---

mcp-name: io.github.leshchenko1979/fast-mcp-telegram