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 "Install 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.
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 |
Prerequisite: Install
uv— see docs if you don't have it. Or use Docker (see Installation Guide).
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, 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
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/alexeyleshchenko/fast-mcp-telegram'
If you have feedback or need assistance with the MCP directory API, please join our Discord server