telegram-mcp
Provides read-only access to Telegram messaging data, including ability to fetch unread messages, search chats, and retrieve message history for a given chat.
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 show my recent unread messages"
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 (движок)
Read-only MCP-читалка своей Telegram (self-host, Telethon). Открытый движок — актив бренда aiaiai. Session живёт на устройстве (keychain), наружу не уходит. v1 = читалка; write-методы не выставлены.
Дизайн и решения — в umbrella-репо telegram-mcp-hosted (docs/decisions.md, architecture.md, build-plan.md).
Раскладка
telegram_mcp/
server.py # entrypoint: FastMCP + авто-дискавери tools/
_app.py # единый FastMCP-инстанс (mcp)
config.py # app-креды (BYO env/.env; broker позже)
qr_render.py # ASCII-QR полублоками (обкатан в спайке) ✅
session_store.py # SessionStore: keychain+Fernet — интерфейс (impl = T2)
client.py # get_client() -> авторизованный TelegramClient — интерфейс (impl = T3)
auth.py # QR-login + 2FA — интерфейс (impl = T4)
tools/
_base.py # mcp, get_client, общие хелперы — единая точка импорта
*.py # по тулу на файл, саморегистрация через @mcp.tool (стабы T5–T12)Related MCP server: Telegram MCP Chigwell
Контракт для авторов тулзов (Wave 1, T5–T12)
Файл тула начинается с
from telegram_mcp.tools._base import mcp, get_client.Регистрация —
@mcp.tool(FastMCP берёт сигнатуру+докстринг в схему). Центрального списка НЕТ — добавил файл, тул появился (авто-дискавери).В Telegram — только через
await get_client().read-only: только
get_*/iter_*/download_*. Ни одного write-вызова.Возвращай JSON-сериализуемое (dict/list), не объекты Telethon.
Трогаешь только свой файл. Не редактируешь
pyproject,server.py,_base.py,_app.py(нужна общая утилита/зависимость → флаг в интеграцию T16). Свой git worktree.
Установка (self-host)
# 1. поставить как CLI (uv сам тянет нужный python ≥3.10)
uv tool install git+https://github.com/expremiental/telegram-mcp
# 2. залогиниться — отсканировать QR своим Telegram
# (app-креды берутся с брокера автоматически, ничего на my.telegram.org создавать не надо)
telegram-mcp login
# 3. подключить в Claude Code / Cursor
claude mcp add -s user telegram-mcp -- telegram-mcp serveПерезапусти хост → спрашивай обычным языком: «сделай дайджест непрочитанного», «найди чат с …», «что писали в … за сегодня».
read-only — выставлены только read-тулзы; ничего не отправляет/не меняет.
session шифрованная в keychain, машину не покидает. Сброс:
telegram-mcp logout.BYO-креды (advanced):
TELEGRAM_API_ID/TELEGRAM_API_HASHв окружении переопределяют брокер.
Dev
uv venv --python 3.12 .venv && uv pip install -e . --python .venv
.venv/bin/telegram-mcp serve # сервер (stdio) · login / logout — онбордингТребует Python ≥3.10 (FastMCP).
Available Tools
10 toolsdigest_unreadA
KILLER-тул: дайджест непрочитанного.
T9: iter_dialogs → топ-N чатов с unread_count>0 → подтянуть per_chat последних сообщений. Чтение НЕ помечает прочитанным (mark_read не зовём). Ограничивать (FloodWait). read-only.
Выбор топа: сортируем чаты по unread_count по убыванию — наверх всплывает самый большой бэклог (что больше всего пропустил). Сообщения внутри чата — newest-first (как отдаёт iter_messages), не помечаем прочитанным.
Inputs: top, per_chat. Returns: result
download_mediaA
Скачать вложение из конкретного сообщения на диск (локально).
T11: get_messages(entity, ids=message_id) → message.download_media(dest). Точечно, не «все фото». read-only (download_*).
Inputs: chat (required), message_id (required), dest. Returns: object
find_chatA
Найти чат ПОИСКОМ (не перебором диалогов): серверный contacts.Search.
contacts.SearchRequest отдаёт РАНЖИРОВАННЫЕ совпадения в my_results (свои контакты/чаты — релевантнее) и results (глобальные публичные); users/chats — лишь пул сущностей для резолва. Берём именно my_results→results, а НЕ весь пул (иначе глобальный шум). Fallback на локальный фильтр диалогов — TODO, только если тест покажет дыру по приватным группам (docs/decisions.md). read-only.
Inputs: query (required), limit. Returns: result
get_historyA
Последние сообщения чата (chat = id/username/ссылка/название → resolve).
T6: iter_messages(entity, limit) → {id, date, sender, text}. read-only.
Inputs: chat (required), limit. Returns: result
get_meA
Текущий аккаунт: id, имя, username. T12: get_me(). read-only.
Inputs: no named parameters. Returns: object
get_participantsC
Участники чата/группы. T12: iter_participants(entity, limit). read-only.
Inputs: chat (required), limit. Returns: result
get_pinnedB
Закреплённые сообщения чата. T12: get_pinned / iter_messages(pinned). read-only.
Inputs: chat (required). Returns: result
list_chatsB
Список диалогов с непрочитанным: title, type, unread_count, последнее сообщение.
T5: iter_dialogs(limit, archived) → chat_brief(...). read-only.
Inputs: limit, archived. Returns: result
resolve_chatA
Точный resolve чата/юзера по username/ссылке/id/точному имени.
T10: resolve_entity(ref) → chat_brief. read-only.
Если не найдено — исключение Telethon (ValueError/UsernameNotOccupiedError и т.п.) пробрасывается наверх, оунер обрабатывает его на интеграции.
Inputs: ref (required). Returns: object
search_in_chatA
Поиск сообщений ВНУТРИ чата по тексту.
T7: iter_messages(entity, search=query, limit). read-only.
Inputs: chat (required), query (required), limit. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a specific Telegram resource and action: account info, unread digest, media download, chat search, message history, chat list, participants, pinned messages, entity resolution, and in-chat search. Potential overlaps (e.g., find_chat vs resolve_chat) are differentiated by search vs exact match, and get_history vs search_in_chat by unfiltered retrieval vs text query.
All tool names follow a consistent verb_noun snake_case pattern (get_me, digest_unread, download_media, find_chat, get_history, list_chats, get_participants, get_pinned, resolve_chat, search_in_chat). The verbs are varied but appropriate to each action, and there are no style mixes or camelCase deviations.
With 10 tools, the set is well-scoped for a Telegram read-only/digest MCP server. Each tool covers a distinct need without unnecessary redundancy, and the count is within the ideal 3-15 range.
The server covers the core read-only workflow: account info, listing chats, unread digests, history, search, media download, participants, pinned messages, and entity resolution. Minor gaps exist, such as no direct tool for getting a single message by ID or detailed user/chat profiles, but these are easily worked around with existing tools.
Maintenance
Related MCP Connectors
Unofficial Telegram MCP server — read, search, reply and react in your own Telegram account.
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceAn MCP server that connects to Telegram as your real user account and exposes read-only tools to read and search messages, list chats and folders, inspect group info, and download media.25 npmMIT
- AlicenseNot gradedqualityBmaintenanceRead-only MCP server for Telegram that enables reading messages and transcribing voice, audio, and video notes via the Telegram API for use with Codex and Claude Code.Apache 2.0
- FlicenseNot gradedqualityBmaintenanceRead-only MCP server for personal Telegram accounts, exposing chat folders, chats, and recent messages via MTProto.-
- AlicenseAqualityBmaintenanceGives MCP clients controlled access to a Telegram user account, letting them search and read messages, inspect chats, and fetch media, with sending or editing messages available only after explicit opt-in. It runs self-hosted over FastMCP and Telethon with strict read-only defaults, OAuth or bearer authentication, and an outbound-only Cloudflare Tunnel.11MIT