leshchenko1979/fast-mcp-telegram

Try the Demo
1. Open https://tg-mcp.l1979.ru/setup
2. **Scan the QR code** from Telegram mobile (Settings → Devices → Scan QR) — no phone typing, no OTP, no 2FA. Or enter your phone number as fallback.
3. Copy your Bearer token from the success page
Then choose your path:
**MCP Client (AI assistants)**
- From the setup page, download the mcp.json file
- Add the server to your AI client and ask: "send hello to my saved messages in telegram"
**Direct API (curl)**
- Run the command below (replace TOKEN with yours):
How It Works
This server sits between your AI agent and Telegram's API:
**What it does:** Authenticates you with Telegram (QR or phone/bot token), exposes 8 AI-friendly tools instead of 80+ micro-APIs, and bridges raw MTProto for power users. Multi-tenant — one server, many users, isolated sessions.
Features
| Feature | Description |
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| :building_construction: **Dual Transport** | Stdio for local MCP clients, HTTP for remote deploys (http-auth production, optional http-no-auth for dev) |
| :closed_lock_with_key: **Multi-User Authentication** | Shared http-auth server: one Bearer token per user, one Telegram account per MCP connection. **QR login** for instant auth — no phone/OTP/2FA. |
| :dart: **AI-Optimized** | 8 consolidated tools vs 80+ micro-tools — context-efficient design, LLM-friendly API, MCP ToolAnnotations |
| :globe_with_meridians: **HTTP-MTProto Bridge** | Direct curl access to any Telegram API method with entity resolution and safety guardrails |
| :shield: **Session ACL** | Opt-in per-principal limits on http-auth (ACL_ENABLED) — chat lanes, read_only, blocked_peers, allow_mtproto, ACL_DENY_UNLISTED_PRINCIPALS; see SECURITY.md |
| :tv: **QR & Web Setup** | Scan QR from Telegram mobile for instant auth (no phone/OTP/2FA) or use phone/code/2FA fallback — live at /setup |
| :label: **One Agent, Multiple Accounts** | Optional PREFIX_MCP_TOOLS_WITH_ACCOUNT — when **one** agent uses several MCP connections (same server, different tokens), prefixes tool names so they do not collide; not needed for standard multi-user hosting |
| :rocket: **MTProto Proxy Support** | Connect via MTProto proxy with automatic Fake TLS (EE prefix) and standard proxy detection |
| :card_file_box: **Unified Session Management** | Single configuration system for setup and server; per-token session files on shared multi-user hosts |
| :cloud: **S3 Session Storage** | Store sessions in S3-compatible object storage for ephemeral hosted deployments (Smithery, Fly.io, Railway) |
| :mag_right: **Intelligent Search** | Global & per-chat message search with multi-query support and intelligent deduplication |
| :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 |
| :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 |