Fast MCP Telegram

🚀 Fast MCP Telegram Server

A production-ready Telegram integration for AI assistants, offering comprehensive search, messaging, and direct API access capabilities.

🌐 Demo

1. Open https://tg-mcp.redevest.ru/setup to start the authentication flow.
2. Once finished, you'll get a ready-to-use mcp.json containing your Bearer token.
3. Use this configuration with your MCP client to explore the capabilities of this MCP server.
4. Or, you can immediately test the HTTP‑MTProto Bridge using 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
• 🚀 Quick Start
• 🏗️ Server Modes
• 🌐 HTTP-MTProto Bridge
• 📚 Documentation
• 🔒 Security
• 🤝 Contributing
• 📄 License

✨ Features

🛠️ Available Tools

📖 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

🌐 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

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

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