fast-mcp-telegram

<img alt="Hero image" src="https://github.com/user-attachments/assets/635236f6-b776-41c7-b6e5-0dd14638ecc1" />

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!"}}'

Features

Feature	Description
:closed_lock_with_key: Multi-User Authentication	Production-ready Bearer token auth with session isolation and LRU cache management
:globe_with_meridians: HTTP-MTProto Bridge	Direct curl access to any Telegram API method with entity resolution and safety guardrails
:mag: Unified Message API	Single get_messages tool for search, browse, read by IDs, and replies - 5 modes in one
:speech_balloon: Universal Replies	Get replies from channel posts, forum topics, or any message with one parameter
:mag_right: Intelligent Search	Global & per-chat message search with multi-query support and intelligent deduplication
:building_construction: Dual Transport	Seamless development (stdio) and production (HTTP) deployment support
:file_folder: Secure File Handling	Rich media sharing with SSRF protection, size limits, album support, optional HTTP attachment streaming
:envelope: Advanced Messaging	Send, edit, reply, post to forum topics, formatting, file attachments, and phone number messaging
:microphone: Voice Transcription	Automatic speech-to-text for Premium accounts with parallel processing and polling
:card_file_box: Unified Session Management	Single configuration system for setup and server, with multi-account support
:busts_in_silhouette: Smart Contact Discovery	Search users, groups, channels with uniform entity schemas, forum detection, profile enrichment
:file_folder: Folder Filtering	Filter chats by dialog folder (archived, custom folders) with integer ID or name matching
:robot: Bot Chat Detection	Bots identified with type: "bot" and filterable via chat_type="bot"
:zap: High Performance	Async operations, parallel queries, connection pooling, and memory optimization
:shield: Production Reliability	Auto-reconnect, structured logging, comprehensive error handling with clear actionable messages
:dart: AI-Optimized	Literal parameter constraints, LLM-friendly API design, and MCP ToolAnnotations
:globe_with_meridians: Web Setup Interface	Browser-based authentication flow with immediate config generation
🚀 MTProto Proxy Support	Connect via MTProto proxy with automatic Fake TLS (EE prefix) and standard proxy detection

Quick Start (pip)

1. Install

pip install fast-mcp-telegram

2. Authenticate

fast-mcp-telegram-setup --api-id="your_api_id" --api-hash="your_api_hash" --phone-number="+123456789"

Or use the web interface: run fast-mcp-telegram and open /setup

Quick Start (uvx)

1. First-time setup

uvx --from fast-mcp-telegram fast-mcp-telegram-setup --api-id="your_api_id" --api-hash="your_api_hash" --phone-number="+123456789"

Sessions are stored in ~/.config/fast-mcp-telegram/ and persist between uvx invocations.

2. Configure MCP Client

STDIO:

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

HTTP_AUTH:

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

4. Start Using

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

Deploy to Production

This project uses GitHub Actions for automatic builds and deployments.

1. Fork this repository
2. Add secrets in GitHub Settings: SSH_HOST, SSH_USER, SSH_PRIVATE_KEY
3. Edit .env in your fork
4. Push to main — deployment happens automatically

Manual deployment: Use scripts/sync-remote-config.sh

See Deployment Guide for details.

Security

• Bearer token authentication with session isolation
• SSRF protection for file downloads
• Dangerous method blocking with opt-in override

See SECURITY.md for details.

Documentation

• Installation Guide - Local and production setup
• Deployment Guide - Docker and VDS deployment
• Tools Reference - Complete tools documentation
• MTProto Bridge - Direct API access via curl
• Operations Guide - Monitoring and troubleshooting

License

MIT License - see LICENSE