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 |
|---|---|
| :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 |
| :envelope: Advanced Messaging | Send, edit, reply, post to forum topics, formatting, file attachments, and phone number messaging |
| :paperclip: Secure File Handling | Rich media sharing with SSRF protection, size limits, album support, optional HTTP attachment streaming |
| :outbox_tray: Inline File Uploads | Data: URI (base64) file uploads in files param — work in all transport modes, filenames preserved, images sent as photos |
| :microphone: Voice Transcription | Automatic speech-to-text for Premium accounts with parallel processing and polling |
| :zap: High Performance | Async operations, parallel queries, and memory-conscious batching |
| :shield: Production Reliability | Auto-reconnect, configurable logging, comprehensive error handling |
Prerequisite: Install
uv— see docs if you don't have it. Or use Docker (see Installation Guide).
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, 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, safety guardrails — 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.alexeyleshchenko/fast-mcp-telegram
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file fast_mcp_telegram-0.44.1.tar.gz.
File metadata
- Download URL: fast_mcp_telegram-0.44.1.tar.gz
- Upload date:
- Size: 428.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
edcb73e37d8e56865e285a96ae9ef67883352789a32c3dcf22d4fe091446463b
|
|
| MD5 |
c1b7d6f2c6837aaf8785ae6a44a50170
|
|
| BLAKE2b-256 |
ac1cb9dc4b6e99f9c3189890184e7dab1b154cd0cc9637572819217fea05313d
|
File details
Details for the file fast_mcp_telegram-0.44.1-py3-none-any.whl.
File metadata
- Download URL: fast_mcp_telegram-0.44.1-py3-none-any.whl
- Upload date:
- Size: 198.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e2bfe526f15d0fd03da9b5e16fd01d15529ac8f8137680cd1ba33d8d688115d0
|
|
| MD5 |
e00bf9649d4b42a0099ca1b2c6117092
|
|
| BLAKE2b-256 |
e6c6b173c7afef134571ff0a8006187299fb005c067493d0e4e26e37762c1c45
|
