io.github.leshchenko1979/fast-mcp-telegram

Install

Config snippet generator goes here (5 client tabs)

README

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

[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docker Ready](https://img.shields.io/badge/Docker-Ready-blue?logo=docker)](https://github.com/leshchenko1979/fast-mcp-telegram)

**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):
```bash
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](#-features)
- [🎯 Design Philosophy](#-design-philosophy)
- [🚀 Quick Start](#-quick-start)
- [🏗️ Server Modes](#️-server-modes)
- [🌐 HTTP-MTProto Bridge](#-http-mtproto-bridge)
- [📚 Documentation](#-documentation)
- [🔒 Security](#-security)
- [🤝 Contributing](#-contributing)
- [📄 License](#-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, and album support |
| ✉️ **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 |