Skip to main content
Glama
Telegram Live MCP

Telegram Live MCP

by sugestr
README.md
# Telegram Live MCP

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

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

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

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

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

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

## Войти в свой Telegram

1. Откройте [my.telegram.org](https://my.telegram.org) под своим аккаунтом.
2. В **API development tools** создайте приложение и получите `api_id` и
   `api_hash`. Название, например `My Telegram Reader`; short name — `myreader`.
3. **Самостоятельно в обычном Терминале**, из папки проекта, выполните:

```bash
.venv/bin/telegram-live login
```

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

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

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

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

Документация Telegram: [получение API ID](https://core.telegram.org/api/obtaining_api_id).
Документация библиотеки: [вход Telethon](https://docs.telethon.dev/en/stable/basic/signing-in.html).

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

После входа:

```bash
.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` реальным путём к скачанной папке;
не заменяйте этим весь файл и не добавляйте вторую одноимённую секцию.

```toml
[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](https://developers.openai.com/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]`, если они нужны.

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

```bash
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:
исходная приватная история, настройки, сессии и переписка не копировались.

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