MCP Telegram Server

An MCP server for interacting with Telegram. It allows searching, sending messages, and managing chats using the Telegram API.

GitHub

Python Version License: MIT Docker Ready

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.redevest.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.redevest.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

FeatureDescription
🔐 Multi-User AuthenticationProduction-ready Bearer token auth with session isolation and LRU cache management
🌐 HTTP-MTProto BridgeDirect curl access to any Telegram API method with entity resolution and safety guardrails
🔍 Intelligent SearchGlobal & per-chat message search with multi-query support and intelligent deduplication
🏗️ Dual TransportSeamless development (stdio) and production (HTTP) deployment support
📁 Secure File HandlingRich media sharing with SSRF protection, size limits, and album support
💬 Advanced MessagingSend, edit, reply with formatting, file attachments, and phone number messaging
🎤 Voice TranscriptionAutomatic speech-to-text for Premium accounts with parallel processing and polling
📊 Unified Session ManagementSingle configuration system for setup and server, with multi-account support
👥 Smart Contact DiscoverySearch users, groups, channels with uniform entity schemas and profile enrichment
⚡ High PerformanceAsync operations, parallel queries, connection pooling, and memory optimization
🛡️ Production ReliabilityAuto-reconnect, structured logging, comprehensive error handling with clear actionable messages
🎯 AI-OptimizedLiteral parameter constraints, LLM-friendly API design, and MCP ToolAnnotations
🌍 Web Setup InterfaceBrowser-based authentication flow with immediate config generation

🛠️ Available Tools

ToolPurposeKey Features
search_messages_globallySearch across all chatsMulti-term queries, date filtering, chat type filtering
search_messages_in_chatSearch within specific chatSupports "me" for Saved Messages, optional query for latest messages
send_messageSend new messageFile attachments (URLs/local), formatting (markdown/html), replies
edit_messageEdit existing messageText formatting, preserves message structure
read_messagesRead specific messages by IDBatch reading, full message content, voice transcription for Premium accounts
find_chatsFind users/groups/channelsMulti-term search, contact discovery, username/phone lookup
get_chat_infoGet detailed profile infoMember counts, bio/about, online status, enriched data
send_message_to_phoneMessage phone numbersAuto-contact management, optional cleanup, file support
invoke_mtprotoDirect Telegram API accessRaw 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="+123456789"

🌐 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": "+123456789"
      }
    }
  }
}

HTTP_AUTH Mode (Production with Bearer Token):

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

4. Start Using!

{"tool": "search_messages_globally", "params": {"query": "hello", "limit": 5}}
{"tool": "send_message", "params": {"chat_id": "me", "message": "Hello from AI!"}}

📝 For detailed installation instructions, see Installation Guide

🏗️ Server Modes

ModeTransportAuthenticationUse Case
STDIOstdioDisabledDevelopment with Cursor IDE
HTTP_NO_AUTHHTTPDisabledDevelopment HTTP server
HTTP_AUTHHTTPRequired (Bearer token)Production deployment

🌐 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!"},
        "resolve": true
      }'

# 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!\"}",
        "resolve": true
      }'

# 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},
        "resolve": true
      }'

📖 For complete MTProto Bridge documentation, see MTProto Bridge Guide

📚 Documentation

🔒 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

Made with ❤️ for the AI automation community

⭐ Star us on GitHub • 💬 Join our community

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

Related Servers