Telegram Live MCP
Provides read-only access to the user's own Telegram account, including finding dialogs, listing account folders, reading chat messages for a period, searching within chats, checking forum topics, downloading message attachments, and exporting selected messages locally. It does not support sending messages, deleting content, joining groups, or marking messages as read.
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 Live MCP Find my chat "Family" and summarize messages from the last week."
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 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
Откройте my.telegram.org под своим аккаунтом.
В API development tools создайте приложение и получите
api_idиapi_hash. Название, напримерMy Telegram Reader; short name —myreader.Самостоятельно в обычном Терминале, из папки проекта, выполните:
.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.
Что доступно модели
Инструмент | Назначение |
| Найти диалог по названию, username или номеру |
| Папки аккаунта и состав выбранной папки |
| Сообщения за период, включая автора, ID и тему форума |
| Поиск внутри конкретного чата |
| Проверить название точной темы форума |
| Скачать вложение конкретного сообщения |
| Сохранить до 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 toolsexport_textBRead-only
Сохранить до20точных сообщений в локальный приватный файл0600. Возвращает путь, число знаков и SHA256 без самого текста.
Inputs: chat_id (required), message_ids (required).
find_dialogsARead-only
Найти чаты аккаунта по куску названия. С этого начинается любое чтение: id чата берётся отсюда, наугад его не бывает. После переноса обычной группы в супергруппу Telegram может вернуть два id одного чата; инструмент помечает проверенную пару и указывает текущий id супергруппы. Одинакового названия без такой связи недостаточно, чтобы считать записи одной группой.
Inputs: query (required), limit, refresh.
get_forum_topicARead-only
Проверить точный forum-topic одного чата по message_thread_id и вернуть его актуальное название. ID берётся из read_chat/search_chat; подбор или переход в корень группы запрещён.
Inputs: chat_id (required), message_thread_id (required).
get_mediaARead-only
Скачать вложение конкретного сообщения и вернуть путь к файлу на диске. Нужно, когда содержательное лежит не в тексте: счёт в PDF, скан, договор, архив, видео или файл любого типа. Номер сообщения берётся из выдачи read_chat — там медиа помечены как «msg 1234». Полный оригинал до фактического download-лимита Telegram кладётся на диск; открывай его дальше обычными средствами сессии.
Inputs: chat_id (required), message_id (required).
list_foldersARead-only
Папки Telegram этого аккаунта и их состав. Без folder — список папок: id, название, сколько чатов, явно добавленные и набранные правилами типов (группы, каналы, контакты…). С folder (название или id из списка) — чаты одной папки: id, название, вид. Папка говорит, к чему относится чат. Состав считается как у коллектора: «только непрочитанные» и «без заглушённых» — свойства отображения, на состав они не влияют.
Inputs: limit, folder, refresh.
read_chatARead-only
Прочитать сообщения чата за период. Возвращает дату, автора, sender_id и @username (когда доступны), текст. Для разбора «что полезного было в группе» бери период пошире и читай подряд.
Inputs: chat_id (required), days, limit, since, +1 more.
search_chatARead-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
Scored across 7 tools
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.
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.
Seven tools is well-scoped for a Telegram read/search/export surface. Each tool covers a meaningful operation without obvious redundancy or bloat.
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
Related MCP Connectors
Your personal Telegram account for AI: read, search and sum up chats. QR login, no API key.
Search, read and reply to your Telegram Business chats, transcribed voice included.
Explore your Messages SQLite database to browse tables and inspect schemas with ease. Run flexible…
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides read-only access to a user's Telegram account via MTProto, enabling chat listing, message retrieval, search, and context fetching.5MIT
- FlicenseNot gradedqualityBmaintenanceRead-only MCP access to a personal Telegram account. Allows querying chats, reading and searching messages via Streamable HTTP.-
- AlicenseNot gradedqualityBmaintenanceEnables 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.13Apache 2.0
- AlicenseAqualityBmaintenanceLocal 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.193MIT