Telegram MCP Server — Model Context Protocol (MCP) gateway for Telegram. 8 context-efficient tools, multi-tenant, MTProto bridge.
Try the Demo
- Open https://tg-mcp.l1979.ru/setup
- 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.
- Copy your Bearer token from the success page
Then choose your path:
MCP Client (AI assistants)
- From the setup page, download the
mcp.jsonfile - 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):
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!"}}'
How It Works
This server sits between your AI agent and Telegram's API:
Your agent → MCP/HTTP → this server → MTProto → Telegram
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 |
|---|---|
| 🏗️ Dual Transport | Stdio for local MCP clients, HTTP for remote deploys (http-auth production, optional http-no-auth for dev) |
| 🔐 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. |
| 🎯 AI-Optimized | 8 consolidated tools vs 80+ micro-tools — context-efficient design, LLM-friendly API, MCP ToolAnnotations |
| 🌐 HTTP-MTProto Bridge | Direct curl access to any Telegram API method with entity resolution and safety guardrails |
| 🛡️ 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 |
| 📺 QR & Web Setup | Scan QR from Telegram mobile for instant auth (no phone/OTP/2FA) or use phone/code/2FA fallback — live at /setup |
| 🏷️ 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 |
| 🚀 MTProto Proxy Support | Connect via MTProto proxy with automatic Fake TLS (EE prefix) and standard proxy detection |
| 🗃️ Unified Session Management | Single configuration system for setup and server; per-token session files on shared multi-user hosts |
| ☁️ S3 Session Storage | Store sessions in S3-compatible object storage for ephemeral hosted deployments (Smithery, Fly.io, Railway) |
| 🔎 Intelligent Search | Global & per-chat message search with multi-query support and intelligent deduplication |
| 🔍 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 |
| 👥 Smart Contact Discovery | Search users, groups, channels with uniform entity schemas, forum detection, profile enrichment |
| 📁 Folder Filtering | Filter chats by dialog folder (archived, custom folders) with integer ID or name matching |
| ✉️ Advanced Messaging | Send, edit, reply, post to forum topics, formatting, file attachments, and phone number messaging |
| 📎 Secure File Handling | Rich media sharing with SSRF protection, size limits, album support, optional HTTP attachment streaming |
| 📤 Inline File Uploads | Data: URI (base64) file uploads in files param — work in all transport modes, filenames preserved, images sent as photos |
| 🎤 Voice Transcription | Automatic speech-to-text for Premium accounts with parallel processing and polling |
| ⚡ High Performance | Async operations, parallel queries, and memory-conscious batching |
| 🛡️ Production Reliability | Auto-reconnect, configurable logging, comprehensive error handling |
Quick Start
1. Install and authenticate
Quickest path (remote server): Open /setup → scan QR → copy token (see Try the Demo).
CLI path (local stdio): Run fast-mcp-telegram-setup once to create a Telegram session — then fast-mcp-telegram serves it:
uvx --from fast-mcp-telegram fast-mcp-telegram-setup \
--api-id="your_api_id" \
--api-hash="your_api_hash" \
--phone-number="+123456789"
Bot token alternative (no phone, no OTP):
Set BOT_API_TOKEN instead of --phone-number. See Installation Guide.
2. Configure MCP Client
stdio mode (local): Add to your MCP client config (e.g. claude_desktop_config.json) — stdio (standard input/output) is the default transport for local MCP clients:
{
"mcpServers": {
"telegram": {
"command": "uvx",
"args": ["fast-mcp-telegram"],
"env": {
"API_ID": "your_api_id",
"API_HASH": "your_api_hash"
}
}
}
}
http-auth mode (remote): Add to your MCP client config (e.g. claude_desktop_config.json):
{
"mcpServers": {
"telegram": {
"url": "https://tg-mcp.l1979.ru/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
Get your token by scanning the QR code on the setup page or see Installation Guide for deploying your own server.
3. 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 Remote Server
Deploy your own MCP server on a VDS — see Installation Guide for step-by-step instructions.
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), date filtering in all modes |
send_message |
Send new message | File attachments (URLs/local/data URIs), classic formatting (markdown/html), parse_mode=rich Rich Messages, reply to forum topics |
edit_message |
Edit existing message | Classic or parse_mode=rich formatting |
find_chats |
Find users/groups/channels | Multi-term search, contact discovery, folder filtering, username/phone lookup |
get_chat_info |
Get detailed profile info | Member counts, bio/about, online status, forum topics, common groups, enriched data |
send_message_to_phone |
Message phone numbers | Auto-contact management, optional cleanup, file support (URLs/data URIs), parse_mode=rich |
invoke_mtproto |
Direct Telegram API (power user) | Raw MTProto methods, entity resolution, PII/credential fields dropped by default (include_sensitive=true for raw) — see MTProto Bridge |
See Tools Reference for detailed documentation with examples.
Documentation
- Installation Guide - Local setup and remote server deployment
- Tools Reference - Complete tools documentation
- MTProto Bridge - Direct API access via curl
- Contributing - Guidelines for contributors
- Security - Security features and best practices
Telemetry
Anonymous tool telemetry since v0.30.1 — heartbeat every 6h, no credentials or message content collected. Opt out with DO_NOT_TRACK=1. See ADR 0005.
Auth flow telemetry since v0.38.0 — atomic events during setup (phone, QR, bot token, reauthorize). Buffered flush on flow completion. See ADR 0008.
License
MIT License - see LICENSE
mcp-name: io.github.leshchenko1979/fast-mcp-telegram
1 maintainer
Metadata
1 maintainer
Release files for fast-mcp-telegram 0.45.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| fast_mcp_telegram-0.45.0.tar.gz | 440.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| fast_mcp_telegram-0.45.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 641.8 kB
Release files / fast_mcp_telegram-0.45.0.tar.gz
| Download URL | fast_mcp_telegram-0.45.0.tar.gz |
|---|---|
| Size | 440.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
37d74bd6a6bb2d5ce2b70995012c482238f1bb6c92b84db670e6f11457764337
|
|
BLAKE2b-256 checksum How to use checksums |
49255337666f26dc2e1a15b172f94b099293854e06e999e1c65068a07279ec77
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / fast_mcp_telegram-0.45.0-py3-none-any.whl
| Download URL | fast_mcp_telegram-0.45.0-py3-none-any.whl |
|---|---|
| Size | 201.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7684259b4fb232180f4ceb477eb3306e1cffa9045d459805227aaadc22178a45
|
|
BLAKE2b-256 checksum How to use checksums |
44c1cd7bbe9388bdae01d8bfb81f7e3a9c69860649d38590f18015d78a808a3a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency log
