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: tdl-mcp

Контракт для авторов тулзов (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).