tgread

Только чтение Telegram MCP-сервер. Позволяет Claude Code читать ваши каналы, группы и личные сообщения — и не даёт ему возможности писать в них.

./install.sh          # pinned venv + ~/.local/bin/tgread + MCP registration
tgread login          # api_id/api_hash, phone, code, 2FA
tgread status         # who am I, is the session live, are perms sane

Почему не один из существующих

Есть хорошие серверы сообщества — chigwell/telegram-mcp имеет 1.5k звёзд, 30 контрибьюторов и настоящую гигиену релизов. Причина написать этот — не недоверие к тому коду. Дело в том, что честная выгода от самостоятельной разработки — это поверхность инструментов и проверяемость, а не количество зависимостей, и именно эти две вещи важны, когда процесс держит сессию Telegram и подаёт агенту текст, контролируемый атакующим.

Писать MTProto вручную было бы безрассудно — Telethon и есть криптография, миграция DC и логика переподключения. Так что он остаётся. Всё, что выше него, — наше.

Related MCP server: telegram-mcp-server

Модель угроз

Чтение каналов означает, что текст, выбранный атакующим, попадает в агента, у которого есть доступ к оболочке — и, как правило, ко всему остальному, что вы подключили: почта, заметки, облачные учётные данные. Это главный риск здесь, и он не устраняется тем, кто написал сервер. Выбор сервера без поверхности записи — одно из немногих смягчений, которое не зависит от хорошего поведения модели.

flowchart TD
    A["hostile channel post<br/>'ignore previous instructions…'"] --> B["tgread read_chat"]
    B --> C["UNTRUSTED envelope<br/>wrapped around every payload"]
    C --> D["agent context"]
    D --> E{"agent tries to act on it"}
    E -->|"send / delete / join"| F["no such tool exists<br/>tools/call → isError"]
    E -->|"raw TL request"| G["guard at _call → WriteBlocked"]
    E -->|"summarise for the user"| H["fine — this is the intended path"]
    style F fill:#1f6f43,color:#fff
    style G fill:#1f6f43,color:#fff

Три уровня, в порядке возрастания того, насколько они переживут ошибку:

1. Никакой инструмент записи не рекламируется. Внедрённой инструкции нечего вызывать.

2. Каждая полезная нагрузка оборачивается в баннер UNTRUSTED CONTENT, называющий её данными, а не инструкциями — включая названия чатов и био, которые тоже контролируются атакующим.

3. Транспортная защита. Telethon пропускает каждый исходящий TL-запрос через TelegramClient._call (68 внутренних мест вызова достигают его через await self(req), а __call__ — однострочный делегат). ReadOnlyClient переопределяет его. Ошибка в этом файле всё равно не может изменить аккаунт.

Защита отказывает закрыто: запрос отклоняется, если имя его TL-класса не начинается с Get/Search/Resolve/Check/Find или он не входит в список разрешённой инфраструктуры из девяти записей. Три запроса, похожие на чтение, отклоняются по имени, потому что у них есть эффекты, которые могут наблюдать другие люди — GetMessagesViews (увеличивает публичный счётчик просмотров), GetBotCallbackAnswer (нажимает инлайн-кнопку), GetInlineBotResults (запрашивает бота от вашего имени). Вложенные запросы обходятся, так что запись не может проехать внутри разрешённой обёртки InvokeWithLayer.

flowchart LR
    R["TL request"] --> W["walk nested .query"]
    W --> D{"in EXPLICIT_DENY?"}
    D -->|yes| X["WriteBlocked"]
    D -->|no| I{"in INFRA_ALLOW?"}
    I -->|yes| P["to the wire"]
    I -->|no| V{"starts with Get/Search/<br/>Resolve/Check/Find?"}
    V -->|yes| P
    V -->|"no — incl. every<br/>name we've never seen"| X
    style X fill:#8b2020,color:#fff
    style P fill:#1f6f43,color:#fff

tgread check запускает это офлайн: 26 запросов на запись заблокировано, 17 чтений разрешено, неизвестные имена закрыты, вложенность проверена. Ни сети, ни сессии, ни учётных данных.

Инструменты

Преднамеренно нет загрузки медиа: получение вложений означает запись байтов, выбранных атакующим, в файловую систему агента. Метаданные сообщения сообщают только тип медиа.

Эксплуатационные заметки

• Используйте вторичный аккаунт. Юзерботы (любой MTProto-клиент, не являющийся официальным приложением) могут быть забанены по ToS. Этот риск одинаков для любого сервера здесь.

• Файл сессии — это bearer-токен для всего аккаунта. Смена пароля Telegram не аннулирует его. Только tgread logout — который отзывает на стороне сервера перед локальным удалением — или Настройки → Устройства. Относитесь к нему как к закрытому ключу SSH.

• pip install telegram-mcp — это не этот пакет и не пакет chigwell. Это имя на PyPI принадлежит несвязанному проекту; передача ему TELEGRAM_API_ID / TELEGRAM_API_HASH отдаст ваши учётные данные стороннему коду. Ничего из этого намеренно не публикуется на PyPI.

• Состояние хранится в одной директории — $TGREAD_STATE_DIR, по умолчанию ~/.local/state/tgread, режим 0700, содержит config.env (0600) и tgread.session (0600). Одна директория для chmod, для резервного копирования, для уничтожения. tgread status сообщает, если права доступа отклонились.

• install.sh использует uv sync --frozen — он устанавливает ровно те версии, которые указаны в закоммиченном uv.lock, и завершается ошибкой, а не пересобирает зависимости. Резолвер, который тихо подхватывает свежий апстрим-релиз, — это путь, по которому скомпрометированный пакет попадает в процесс, держащий вашу сессию.

Структура

Команды

tgread login      interactive: API credentials, phone, login code, 2FA
tgread status     who am I, is the session valid, are permissions sane
tgread logout     revoke server-side, then delete locally
tgread check      offline self-test of the read-only guard
tgread serve      speak MCP over stdio — what Claude Code runs

login и logout используют обычный клиент, а не защищённый: защита существует, чтобы ограничивать агента, а не человека за терминалом, устанавливающего или отзывающего сессию. Всё, к чему прикасается MCP-сервер, проходит через ReadOnlyClient.