{
  "markdown": "<img alt=\"Hero image\" src=\"https://github.com/user-attachments/assets/635236f6-b776-41c7-b6e5-0dd14638ecc1\" />\n\n**Telegram MCP Server** — Model Context Protocol (MCP) gateway for Telegram. 8 context-efficient tools, multi-tenant, MTProto bridge.\n\n> Canonical GitHub repository: [alexeyleshchenko/fast-mcp-telegram](https://github.com/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 remains `pip install fast-mcp-telegram` or `uvx --from fast-mcp-telegram`; PyPI is the stable pointer.\n\n## Try the Demo\n\n1. Open https://tg-mcp.l1979.ru/setup\n2. **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.\n3. Copy your Bearer token from the success page\n\nThen choose your path:\n\n**MCP Client (AI assistants)**\n- From the [setup page](/setup), download the `mcp.json` file\n- Add the server to your AI client and ask: \"send hello to my saved messages in telegram\"\n\n**Direct API (curl)**\n- Run the command below (replace TOKEN with yours):\n```bash\ncurl -X POST \"https://tg-mcp.l1979.ru/mtproto-api/messages.SendMessage\" \\\n  -H \"Authorization: Bearer TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"params\": {\"peer\": \"me\", \"message\": \"Hello!\"}}'\n```\n\n[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Docker Ready](https://img.shields.io/badge/Docker-Ready-blue?logo=docker)](https://github.com/alexeyleshchenko/fast-mcp-telegram)\n[![Health Status](https://gatus.l1979.ru/api/v1/endpoints/apps_fast-mcp-telegram/uptimes/30d/badge.svg)](https://gatus.l1979.ru/endpoints/apps_fast-mcp-telegram)\n[![Glama Score](https://glama.ai/mcp/servers/alexeyleshchenko/fast-mcp-telegram/badges/score.svg)](https://glama.ai/mcp/servers/alexeyleshchenko/fast-mcp-telegram)\n\n## How It Works\n\nThis server sits between your AI agent and Telegram's API:\n\n```\nYour agent → MCP/HTTP → this server → MTProto → Telegram\n```\n\n**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.\n\n## Features\n\n\n| Feature                                                                                             | Description                                                                                                    |\n| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |\n| :building_construction: **[Dual Transport](docs/Installation.md#overview)**                         | Stdio for local MCP clients, HTTP for remote deploys (`http-auth` production, optional `http-no-auth` for dev) |\n| :closed_lock_with_key: **[Multi-User Authentication](docs/Installation.md#remote-setup-http-auth)** | Shared `http-auth` server: one Bearer token per user, one Telegram account per MCP connection. **QR login** for instant auth — no phone/OTP/2FA. |\n| :dart: **[AI-Optimized](docs/Tools-Reference.md#overview)**                                         | 8 consolidated tools vs 80+ micro-tools — context-efficient design, LLM-friendly API, MCP ToolAnnotations     |\n| :globe_with_meridians: **[HTTP-MTProto Bridge](docs/MTProto-Bridge.md#key-benefits)**               | Direct curl access to any Telegram API method with entity resolution and safety guardrails                     |\n| :shield: **[Session ACL](docs/Installation.md#session-acl-http-auth)** | 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](SECURITY.md#opt-in-session-acl-http-auth) |\n| :tv: **[QR & Web Setup](docs/Installation.md#web-setup-interface)**                              | Scan QR from Telegram mobile for instant auth (no phone/OTP/2FA) or use phone/code/2FA fallback — live at `/setup` |\n| :label: **[One Agent, Multiple Accounts](docs/Installation.md#multi-account-mcp-tool-prefix)**     | 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 |\n| :rocket: **[MTProto Proxy Support](docs/Installation.md#mtproto-proxy)**                            | Connect via MTProto proxy with automatic Fake TLS (EE prefix) and standard proxy detection                     |\n| :card_file_box: **[Unified Session Management](docs/Installation.md#configuration-reference)**      | Single configuration system for setup and server; per-token session files on shared multi-user hosts          |\n| :cloud: **[S3 Session Storage](docs/Installation.md#s3-session-storage-optional)**                  | Store sessions in S3-compatible object storage for ephemeral hosted deployments (Smithery, Fly.io, Railway)  |\n| :mag_right: **[Intelligent Search](docs/Search-Guidelines.md#what-works)**                          | Global & per-chat message search with multi-query support and intelligent deduplication                        |\n| :mag: **[Unified Message API](docs/Tools-Reference.md#2-read)**                                     | Single `get_messages` tool for search, browse, read by IDs, and replies - 5 modes in one                       |\n| :speech_balloon: **[Universal Replies](docs/Tools-Reference.md#2-read)**                            | Get replies from channel posts, forum topics, or any message with one parameter                                |\n| :busts_in_silhouette: **[Smart Contact Discovery](docs/Tools-Reference.md#1-discovery)**            | Search users, groups, channels with uniform entity schemas, forum detection, profile enrichment                |\n| :file_folder: **[Folder Filtering](docs/Tools-Reference.md#1-discovery)**                           | Filter chats by dialog folder (archived, custom folders) with integer ID or name matching                      |\n| :envelope: **[Advanced Messaging](docs/Tools-Reference.md#3-write)**                                | Send, edit, reply, post to forum topics, formatting, file attachments, and phone number messaging              |\n| :paperclip: **[Secure File Handling](docs/Tools-Reference.md#3-write)**                             | Rich media sharing with SSRF protection, size limits, album support, optional HTTP attachment streaming        |\n| :outbox_tray: **[Inline File Uploads](docs/Tools-Reference.md#3-write)**                           | Data: URI (base64) file uploads in `files` param — work in all transport modes, filenames preserved, images sent as photos |\n| :microphone: **[Voice Transcription](docs/Tools-Reference.md#get_messages)**                       | Automatic speech-to-text for Premium accounts with parallel processing and polling                             |\n| :zap: **High Performance**                                                                          | Async operations, parallel queries, and memory-conscious batching                                              |\n| :shield: **Production Reliability**                                                                 | Auto-reconnect, configurable logging, comprehensive error handling                                               |\n\n## Quick Start\n\n### 1. Install and authenticate\n\n**Quickest path (remote server):** Open `/setup` → scan QR → copy token (see [Try the Demo](#try-the-demo)).\n\n**CLI path (local stdio):** Run `fast-mcp-telegram-setup` once to create a Telegram session — then `fast-mcp-telegram` serves it:\n```bash\nuvx --from fast-mcp-telegram fast-mcp-telegram-setup \\\n  --api-id=\"your_api_id\" \\\n  --api-hash=\"your_api_hash\" \\\n  --phone-number=\"+123456789\"\n```\n\n**Bot token alternative (no phone, no OTP):**\nSet `BOT_API_TOKEN` instead of `--phone-number`. See [Installation Guide](docs/Installation.md).\n\n### 2. Configure MCP Client\n\n**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:\n```json\n{\n  \"mcpServers\": {\n    \"telegram\": {\n      \"command\": \"uvx\",\n      \"args\": [\"fast-mcp-telegram\"],\n      \"env\": {\n        \"API_ID\": \"your_api_id\",\n        \"API_HASH\": \"your_api_hash\"\n      }\n    }\n  }\n}\n```\n\n**http-auth mode (remote):** Add to your MCP client config (e.g. `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"telegram\": {\n      \"url\": \"https://tg-mcp.l1979.ru/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\nGet your token by scanning the QR code on the [setup page](/setup) or see [Installation Guide](docs/Installation.md) for deploying your own server.\n\n### 3. Start Using\n```json\n{\"tool\": \"search_messages_globally\", \"params\": {\"query\": \"hello\", \"limit\": 5}}\n{\"tool\": \"get_messages\", \"params\": {\"chat_id\": \"me\", \"limit\": 10}}\n{\"tool\": \"send_message\", \"params\": {\"chat_id\": \"me\", \"message\": \"Hello!\"}}\n```\n\n## Deploy to Remote Server\n\nDeploy your own MCP server on a VDS — see [Installation Guide](docs/Installation.md) for step-by-step instructions.\n\n## Available Tools\n\n| Tool | Purpose | Key Features |\n|------|---------|--------------|\n| `search_messages_globally` | Search across all chats | Multi-term queries, date filtering, chat type filtering |\n| `get_messages` | Unified message retrieval | Search/browse, read by IDs, get replies (posts/topics/messages), date filtering in all modes |\n| `send_message` | Send new message | File attachments (URLs/local/data URIs), classic formatting (markdown/html), `parse_mode=rich` Rich Messages, reply to forum topics |\n| `edit_message` | Edit existing message | Classic or `parse_mode=rich` formatting |\n| `find_chats` | Find users/groups/channels | Multi-term search, contact discovery, folder filtering, username/phone lookup |\n| `get_chat_info` | Get detailed profile info | Member counts, bio/about, online status, forum topics, common groups, enriched data |\n| `send_message_to_phone` | Message phone numbers | Auto-contact management, optional cleanup, file support (URLs/data URIs), `parse_mode=rich` |\n| `invoke_mtproto` | Direct Telegram API (power user) | Raw MTProto methods, entity resolution, safety guardrails — see [MTProto Bridge](docs/MTProto-Bridge.md) |\n\nSee [Tools Reference](docs/Tools-Reference.md) for detailed documentation with examples.\n\n\n## Documentation\n\n- [Installation Guide](docs/Installation.md) - Local setup and remote server deployment\n- [Tools Reference](docs/Tools-Reference.md) - Complete tools documentation\n- [MTProto Bridge](docs/MTProto-Bridge.md) - Direct API access via curl\n- [Contributing](CONTRIBUTING.md) - Guidelines for contributors\n- [Security](SECURITY.md) - Security features and best practices\n\n## Telemetry\n\nAnonymous 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](docs/adr/0005-anonymous-tool-telemetry.md).\n\nAuth flow telemetry since v0.38.0 — atomic events during setup (phone, QR, bot token, reauthorize). Buffered flush on flow completion. See [ADR 0008](docs/adr/0008-auth-telemetry-events.md).\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n\nmcp-name: io.github.alexeyleshchenko/fast-mcp-telegram\n",
  "bytes": 11598,
  "sha": "c7021160f9c855fdf8bb920e3c2f81e31eb02302f7b030d1e31a944925324329",
  "repo_slug": "alexeyleshchenko/fast-mcp-telegram",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_alexeyleshchenko_fast_mcp_tele_3deffaec/readme"
}