Skip to main content
Glama
telegram-mcp

telegram-mcp

by expremiental

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 tools
digest_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

    A3.7/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      An 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 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Read-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
    • F
      license
      Not graded
      quality
      B
      maintenance
      Read-only MCP server for personal Telegram accounts, exposing chat folders, chats, and recent messages via MTProto.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Gives 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.
      11
      MIT