The Telegram MCP Server is a Model Context Protocol (MCP) gateway that connects AI agents to Telegram's MTProto API. It provides 8 context-efficient tools: search_messages_globally (cross-chat search with date/type filters), get_messages (unified message retrieval including browse, search, by-ID, and forum threads), send_message (text/files with formatting and reply support), edit_message (modify text), find_chats (discover users/groups/channels by name, username, phone, with folder/date filters), get_chat_info (profile/metadata details), send_message_to_phone (direct phone messaging with temporary contact), and invoke_mtproto (raw API access with safety guardrails). It supports multi-user with QR/phone/bot authentication, session isolation, optional S3 storage, and runs over stdio or HTTP, with production features like proxy support and telemetry.
Provides tools for interacting with Telegram's API, enabling AI agents to send messages, search chats, retrieve messages, and manage Telegram conversations via MTProto.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Telegram MCP Server send hello to my saved messages in telegram"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Telegram MCP Server — Model Context Protocol (MCP) gateway for Telegram. 8 context-efficient tools, multi-tenant, MTProto bridge.
Canonical GitHub repository: alexeyleshchenko/fast-mcp-telegram. This is the same project previously published under
leshchenko1979/fast-mcp-telegram. The old GitHub URL is a public 404. Install remainspip install fast-mcp-telegramoruvx --from fast-mcp-telegram; PyPI is the stable pointer.
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.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):
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!"}}'
Related MCP server: MCP Telegram
This server sits between your AI agent and Telegram's API:
Your agent → MCP/HTTP → this server → MTProto → TelegramWhat 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.
Feature | Description |
:building_construction: Dual Transport | Stdio for local MCP clients, HTTP for remote deploys ( |
:closed_lock_with_key: Multi-User Authentication | Shared |
: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 |
:tv: QR & Web Setup | Scan QR from Telegram mobile for instant auth (no phone/OTP/2FA) or use phone/code/2FA fallback — live at |
:label: One Agent, Multiple Accounts | Optional |
: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 |
: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 |
: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 |
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.
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.
{"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 your own MCP server on a VDS — see Installation Guide for step-by-step instructions.
Tool | Purpose | Key Features |
| Search across all chats | Multi-term queries, date filtering, chat type filtering |
| Unified message retrieval | Search/browse, read by IDs, get replies (posts/topics/messages), date filtering in all modes |
| Send new message | File attachments (URLs/local/data URIs), classic formatting (markdown/html), |
| Edit existing message | Classic or |
| Find users/groups/channels | Multi-term search, contact discovery, folder filtering, username/phone lookup |
| Get detailed profile info | Member counts, bio/about, online status, forum topics, common groups, enriched data |
| Message phone numbers | Auto-contact management, optional cleanup, file support (URLs/data URIs), |
| Direct Telegram API (power user) | Raw MTProto methods, entity resolution, safety guardrails — see MTProto Bridge |
See Tools Reference for detailed documentation with examples.
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
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.
MIT License - see LICENSE
mcp-name: io.github.alexeyleshchenko/fast-mcp-telegram
Replace the text of an existing message in a Telegram chat. Only works on messages sent by the authenticated account. Cannot edit media or other message attributes — text only. parse_mode: classic markdown/html/auto or rich (Rich Message; dialect auto-detected). Success: dict with message_id, date, chat, text, status='edited', and edit_date (rich messages also set rich=true and rich_format). Error: dict with ok=false and error string (e.g. message not found or not editable). Use edit_message to update a previously sent message; use send_message to create new ones. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Inputs: chat_id (required), message (required), message_id (required), parse_mode. Returns: Return type for ``send_message`` and ``edit_message``.
Find users/groups/channels by name, username, or phone. Comma-separated usernames are searched in parallel and results are merged round-robin. Global search (query required) searches all Telegram; with min_date, max_date, or filter, search uses dialog list or a named filter; include_peers filters use last-activity from GetPeerDialogs; flag-based filters use dialog list dates. Success: dict with key chats (list of chat objects). Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Inputs: limit, query, folder, public, +3 more. Returns: Return type for ``find_chats``.
Load profile and metadata for one user, bot, group, or channel. Success: info dict; forum chats may include topics up to topics_limit; user targets may include common_chats up to common_chats_limit. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Inputs: chat_id (required), topics_limit. Returns: Return type for ``get_chat_info``.
Read or search messages in one chat: browse latest, search text, fetch by ids, or load replies to a message (comments, forum topics, threads). Use from_user to filter by sender (server-side, per-chat only). Use context to include neighboring messages and reply chains around each result. Use include_replies to fetch up to 5 direct replies per result. Do not combine message_ids with query or reply_to_id. Success: messages, has_more, optional total_count and discussion fields. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Inputs: chat_id (required), limit, query, context, +9 more. Returns: Return type for ``search_messages_globally`` and ``get_messages``.
Low-level Telegram API (MTProto) invoke for methods not wrapped by other tools. Dangerous methods require allow_dangerous=true. Success: API result dict or normalized error. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Inputs: params_json (required), method_full_name (required), resolve, allow_dangerous. Returns: Return type for ``invoke_mtproto``. The success payload is a JSON-safe dict who…
Search all Telegram chats at once (not scoped to one chat). Comma-separated query terms; optional filters by date, chat kind, and public username. Success: message list and metadata dict. Global search ignores include_total_count. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Inputs: query (required), limit, public, max_date, +4 more. Returns: Return type for ``search_messages_globally`` and ``get_messages``.
Send text and optional file attachments to a Telegram chat. Supports reply-to (including forum topics and channel discussion groups), parse_mode: classic markdown/html/auto (entities) or rich (Rich Message document; dialect auto-detected). parse_mode=rich cannot be combined with files. File attachments as http(s) URLs, local paths, or data: URIs. When files are provided, the message text becomes a caption. For channel posts with reply_to_id, automatically posts in the linked discussion group. Success: dict with message_id, date, chat, text, status='sent', and sender info (rich messages also set rich=true and rich_format). Error: dict with ok=false and error string. Use send_message to create new messages; use edit_message to modify existing ones. Use send_message_to_phone when targeting a phone number instead of a chat_id. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Inputs: chat_id (required), message (required), files, parse_mode, +1 more. Returns: Return type for ``send_message`` and ``edit_message``.
Send to a phone number: may create a temporary contact, then send text or files. Supports parse_mode: classic markdown/html/auto or rich (Rich Message; dialect auto-detected). parse_mode=rich cannot be combined with files. Success: send result plus contact_was_new / contact_removed when applicable. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Inputs: message (required), phone_number (required), files, last_name, +4 more. Returns: Return type for ``send_message_to_phone``.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 8 tools
Each tool targets a distinct action: finding chats, reading/searching messages in one chat, searching globally, sending, editing, and fetching chat info. The two send tools are clearly separated by target (chat_id vs phone), and global search vs per-chat search is explicitly scoped.
Tool names mostly follow a clean verb_noun pattern in snake_case (get_messages, send_message, edit_message, get_chat_info). Minor deviations like search_messages_globally and send_message_to_phone add modifiers, but the pattern remains predictable and readable.
Eight tools is a well-scoped size for a Telegram MCP server. Each tool covers a meaningful capability without unnecessary fragmentation, and the low-level invoke_mtproto tool rounds out the surface without bloating it.
Core workflows are covered: finding chats, reading/searching messages, sending, editing, and getting chat info. Obvious gaps like message deletion or marking messages read are not wrapped, but invoke_mtproto provides an escape hatch, so agents are not entirely blocked.
Hosted Telegram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
