Skip to main content
Glama
Telegram Live MCP

Telegram Live MCP

by sugestr

Telegram Live MCP

Локальный коннектор для чтения своего Telegram в Codex на macOS. Это самостоятельная версия telegram-live: исходный проект и чужие аккаунты для установки не нужны. У каждого пользователя собственный вход.

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

Быстрая установка на Mac

Нужны macOS, Python 3.10+ и установленный Codex. Intel и Apple Silicon используют одни команды; автоматическая проверка выполнена на Apple Silicon.

git clone https://github.com/sugestr/telegram-live-mcp.git
cd telegram-live-mcp
bash install.sh

Установщик создаёт .venv внутри этой папки. Он не меняет существующие MCP-подключения и не выполняет вход в Telegram.

Related MCP server: my-tg-mcp

Войти в свой Telegram

  1. Откройте my.telegram.org под своим аккаунтом.

  2. В API development tools создайте приложение и получите api_id и api_hash. Название, например My Telegram Reader; short name — myreader.

  3. Самостоятельно в обычном Терминале, из папки проекта, выполните:

.venv/bin/telegram-live login

При первом входе введите API ID и API hash. Hash и облачный пароль вводятся скрыто. Отсканируйте QR: Telegram на телефоне → Настройки → Устройства → Подключить устройство. Если включён облачный пароль, введите его в Терминале. Символы при вводе не отображаются — это нормально.

Вход по коду вместо QR:

.venv/bin/telegram-live login --phone

Номер, код и пароль вводит сам человек. Не вставляйте их в диалог с Codex. Проверьте имя аккаунта, которое команда покажет после успешного входа. Файл авторизации с другого компьютера или от другого человека не нужен.

Документация Telegram: получение API ID. Документация библиотеки: вход Telethon.

Подключить к Codex

После входа:

.venv/bin/telegram-live register-codex

Команда использует установленный codex mcp add, сохраняет абсолютный путь к программе и не записывает API ID/hash в настройки Codex. Если подключение telegram-live уже есть, команда остановится и сохранит его как есть.

Перезапустите Codex и начните новый чат. Например:

Найди мой чат «Название чата» в Telegram и кратко перескажи сообщения за неделю.

Если CLI Codex не найден

В ~/.codex/config.toml можно добавить следующую секцию. Замените /ABSOLUTE/PATH/telegram-live-mcp реальным путём к скачанной папке; не заменяйте этим весь файл и не добавляйте вторую одноимённую секцию.

[mcp_servers.telegram-live]
command = "/ABSOLUTE/PATH/telegram-live-mcp/.venv/bin/telegram-live"
args = ["serve"]
startup_timeout_sec = 20
tool_timeout_sec = 90

Для локального STDIO-сервера используется команда serve, а не URL GitHub и не codex mcp login (последняя команда относится к OAuth-серверам). Официальная документация Codex MCP.

Что доступно модели

Инструмент

Назначение

find_dialogs

Найти диалог по названию, username или номеру

list_folders

Папки аккаунта и состав выбранной папки

read_chat

Сообщения за период, включая автора, ID и тему форума

search_chat

Поиск внутри конкретного чата

get_forum_topic

Проверить название точной темы форума

get_media

Скачать вложение конкретного сообщения

export_text

Сохранить до 20 выбранных сообщений локально, без текста в ответе MCP

Доступны диалоги именно вошедшего аккаунта, включая личные и архивные. Папки не являются ограничением доступа. Используйте коннектор только в доверенном окружении Codex и для чатов, которые хотите дать ему прочитать.

Где хранятся данные

По умолчанию: ~/Library/Application Support/Telegram Live MCP/. Внутри — credentials.json, account.session, привязка сессии к этому компьютеру, журнал запросов, скачанные вложения и экспортированный текст. Папки имеют права 0700, секретные и созданные файлы — 0600. Журнал обязателен: если записать его нельзя, чтение не выполняется. В журнале есть названия/ID чатов и поисковые запросы; тексты сообщений туда не записываются. Это локальные приватные данные, их не нужно публиковать.

Сам сервер работает локально; сетевое чтение идёт в Telegram через Telethon. Запрошенные тексты попадают в контекст Codex и обрабатываются по правилам вашего аккаунта Codex. Автоматического фонового мониторинга нет.

Сессия Telegram технически даёт полноценный вход в аккаунт: ограничение на чтение реализовано этим сервером, а не отдельными Telegram OAuth-правами. Не передавайте .session и API hash другим людям. На другом Mac войдите заново. Отозвать доступ можно в Telegram → Настройки → Устройства: завершить сессию Telegram Live MCP и перезапустить Codex.

Для отдельного локального профиля задайте TELEGRAM_LIVE_HOME одинаково перед login и register-codex; существующий профиль не переключайте под работающим сервером. Одна установка по умолчанию — один аккаунт.

Голосовые сообщения — необязательно

Скачивание аудио работает сразу. Для локальной расшифровки дополнительно нужны ffmpeg, whisper-cli и модель whisper.cpp. Путь к модели можно задать через TELEGRAM_LIVE_WHISPER_MODEL; стандартный путь — ~/Library/Application Support/Telegram Live MCP/models/ggml-large-v3-turbo.bin. Эти большие компоненты установщик автоматически не скачивает. При их отсутствии сервер сообщает, что аудио скачано, но не расшифровано; текст не выдумывается. Для GUI Codex передайте переменные в секции [mcp_servers.telegram-live.env], если они нужны.

Обновление и проверка

git pull --ff-only
bash install.sh
.venv/bin/python -m unittest discover -v

После обновления перезапустите Codex. Повторный вход не требуется, пока сессия действительна. Установщик не переносит её и не сбрасывает.

Проверенный объём

Независимая чистая установка и MCP STDIO discovery проверяются без Telegram и без чьих-либо секретов. Тесты используют искусственные диалоги и проверяют рендеринг, папки, обновление кеша, запрет записи, отдельное хранение состояния и ошибки до входа. Реальный вход нового пользователя и чтение его Telegram нужно завершить на его Mac — это не подтверждается тестами пакета.

Происхождение

Извлечено из собственного tg-archive на снимке 37fa2b44705e52356ecec74c2604a59444efe05a (2026-11-14). Сохранены алгоритмы чтения, папок, sender/topic ID, миграций групп, экспорта и локальной расшифровки. Добавлены автономные настройки, отдельный вход и установка в Codex. В публичном репозитории новая история Git: исходная приватная история, настройки, сессии и переписка не копировались.

Available Tools

7 tools
export_textB
Read-only

Сохранить до20точных сообщений в локальный приватный файл0600. Возвращает путь, число знаков и SHA256 без самого текста.

Inputs: chat_id (required), message_ids (required).

find_dialogsA
Read-only

Найти чаты аккаунта по куску названия. С этого начинается любое чтение: id чата берётся отсюда, наугад его не бывает. После переноса обычной группы в супергруппу Telegram может вернуть два id одного чата; инструмент помечает проверенную пару и указывает текущий id супергруппы. Одинакового названия без такой связи недостаточно, чтобы считать записи одной группой.

Inputs: query (required), limit, refresh.

get_forum_topicA
Read-only

Проверить точный forum-topic одного чата по message_thread_id и вернуть его актуальное название. ID берётся из read_chat/search_chat; подбор или переход в корень группы запрещён.

Inputs: chat_id (required), message_thread_id (required).

get_mediaA
Read-only

Скачать вложение конкретного сообщения и вернуть путь к файлу на диске. Нужно, когда содержательное лежит не в тексте: счёт в PDF, скан, договор, архив, видео или файл любого типа. Номер сообщения берётся из выдачи read_chat — там медиа помечены как «msg 1234». Полный оригинал до фактического download-лимита Telegram кладётся на диск; открывай его дальше обычными средствами сессии.

Inputs: chat_id (required), message_id (required).

list_foldersA
Read-only

Папки Telegram этого аккаунта и их состав. Без folder — список папок: id, название, сколько чатов, явно добавленные и набранные правилами типов (группы, каналы, контакты…). С folder (название или id из списка) — чаты одной папки: id, название, вид. Папка говорит, к чему относится чат. Состав считается как у коллектора: «только непрочитанные» и «без заглушённых» — свойства отображения, на состав они не влияют.

Inputs: limit, folder, refresh.

read_chatA
Read-only

Прочитать сообщения чата за период. Возвращает дату, автора, sender_id и @username (когда доступны), текст. Для разбора «что полезного было в группе» бери период пошире и читай подряд.

Inputs: chat_id (required), days, limit, since, +1 more.

search_chatA
Read-only

Поиск по одному чату силами самого Telegram. Дешевле, чем читать всё подряд, когда известно ключевое слово. Формат как у read_chat: message_id, sender_id и @username (когда доступны).

Inputs: query (required), chat_id (required), limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: dialog/folder discovery, message reading, keyword search within a chat, text export, media download, and forum-topic lookup. The descriptions explicitly explain prerequisites and boundaries, so overlapping-sounding actions like read_chat vs search_chat remain easy to distinguish.

    Naming Consistency5/5

    All seven tools use snake_case with a verb_noun structure (get_forum_topic, find_dialogs, list_folders, read_chat, search_chat, export_text, get_media). There are no mixed conventions or vague standalone verbs.

    Tool Count5/5

    Seven tools is well-scoped for a Telegram read/search/export surface. Each tool covers a meaningful operation without obvious redundancy or bloat.

    Completeness4/5

    The set covers the main read-only workflow: discover chats/folders, read messages, search, export text, download media, and resolve forum topics. Minor gaps remain, such as listing forum topics directly and richer chat/message metadata, but agents can mostly work around these via read_chat and search_chat.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Provides read-only access to a user's Telegram account via MTProto, enabling chat listing, message retrieval, search, and context fetching.
      5
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Read-only MCP access to a personal Telegram account. Allows querying chats, reading and searching messages via Streamable HTTP.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to search and analyze a Telegram account as a read-only knowledge source, allowing chat discovery, message search, history reading, contact inspection, and media download without exposing any mutating Telegram tools.
      13
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Local Telegram MCP for Codex on macOS and Windows, Gemini CLI on macOS, and ChatGPT Work on Windows: search chats, read history and threads, download attachments, transcribe voice notes, and optionally prepare, send, or edit messages with user approval.
      19
      3
      MIT