telegram-mcp-ag

Даёт ассистентам Claude и ChatGPT читать ваш Telegram и расшифровывать голосовые сообщения, видео-кружки и аудио. Только чтение: отправлять сообщения или менять что-либо в вашем аккаунте это не умеет и не будет. Сохранение файлов из сообщений на компьютер — по желанию, включается отдельно (см. ниже).

Что подготовить заранее

Перед установкой понадобятся api_id и api_hash — это данные вашего Telegram-приложения, не пароль. Получить их можно бесплатно на my.telegram.org/apps (нужно один раз войти по номеру телефона, дальше — заполнить короткую форму создания приложения). Установщик попросит вставить эти два значения в самом начале.

Как получить api_id и api_hash:

1. Откройте в браузере my.telegram.org и введите свой номер телефона в международном формате (например, +7...).

2. Telegram пришлёт код входа — не SMS, а сообщение в самом приложении Telegram (как код для входа с нового устройства). Введите этот код на сайте.

3. После входа откройте API development tools (если это первый вход — сайт сам предложит эту форму).

4. Заполните форму создания приложения:

   • App title — любое название, видите только вы (например, «Мой ассистент»);

   • Short name — короткое имя без пробелов (например, my-assistant);

   • Platform — выберите любой пункт, например «Desktop» или «Other», на работу не влияет;

   • остальные поля необязательны, можно оставить пустыми.

5. Нажмите Create application.

6. На открывшейся странице появятся два значения — App api_id (число) и App api_hash (строка из букв и цифр). Их и нужно скопировать и вставить туда, где просит установщик.

Это данные приложения, а не пароль от аккаунта, но всё равно держите их при себе — не публикуйте, не отправляйте в чат с ассистентом и не кладите в код.

Related MCP server: telegram-mcp

Установка

Если раньше не пользовались ни одним из приложений на компьютере — проще и удобнее всего установить Claude Desktop, затем выполнить установку данного ассистента и добавить скил в приложении Claude Desktop как описано ниже.

Claude Desktop, ChatGPT Desktop (режим Work), Claude Code CLI, Codex CLI — через терминал

macOS и Linux — вставьте в терминал:

curl -fsSL https://raw.githubusercontent.com/agroznykh/telegram-mcp-ag/main/install.sh | bash

Windows — вставьте в PowerShell:

$f = "$env:TEMP\telegram-mcp-ag-install.ps1"; iwr 'https://raw.githubusercontent.com/agroznykh/telegram-mcp-ag/main/install.ps1' -OutFile $f; & $f

Скрипт попросит указать api_id и api_hash, покажет QR-код прямо в терминале и попросит указать пароль двухфакторной аутентификации (если он у вас установлен в приложении Telegram). Чтобы отсканировать QR-код, зайдите в Telegram на телефоне → Настройки → Устройства → Подключить устройство.

После установки перезапустите то приложение, которым пользуетесь (если оно уже было открыто) — новые инструменты появятся в новом чате.

Скилл telegram-digest для Claude Desktop (обязательный шаг)

Установите скилл telegram-digest — он заметно облегчит работу с Telegram в приложении. В Claude Desktop его нужно добавить самостоятельно.

1. Включите скиллы в настройках аккаунта

В Claude Desktop (или на claude.ai) откройте значок профиля → Settings → Capabilities и включите «Code execution and file creation», если выключено — без этого скиллы не работают вообще. На рабочем/корпоративном аккаунте этот переключатель может быть у администратора, в Organization settings → Skills.

2. Подключите скилл

Значок профиля → Settings → Customize → вкладка Skills → Add → Upload a skill → выберите telegram-digest-skill-<версия>.zip в Загрузках. Скилл появится в списке. Загруженную версию видно на вкладке Содержимое в поле Version.

Скилл для ChatGPT Desktop и Codex

Установщик сам кладёт скилл в ~/.agents/skills/telegram-digest (на Windows — %USERPROFILE%\.agents\skills), если находит Codex CLI или ChatGPT Desktop. Руками ничего подключать не нужно. Если скилл не появился в новом чате, перезапустите приложение.

Что не поддерживается

Веб-версии и мобильные приложения — ни у Claude (claude.ai), ни у ChatGPT — подключить нельзя, ни на каких ОС.

А также режим Chat в ChatGPT Desktop: MCP-инструменты в нём не подключаются, работает только режим Work. В Claude Desktop инструменты доступны и в Chat, и в Cowork. Проверено на Claude for Mac 3.6556.2 и ChatGPT 26.1016.62342; в других версиях может отличаться (подробности — в TECHNICAL.md).

Как этим пользоваться

После установки просто спрашивайте у ассистента — Telegram-инструменты работают как обычная часть разговора, отдельно их вызывать не нужно. Спросить можно про содержимое любого чата, который виден вашему аккаунту, — личного, группового или канала. Например:

• «Перескажи, что нового в чате „Семья“ за сегодня»

• «Есть голосовые от Афанасия за последние два дня? Перескажи текстом»

• «Что писали в рабочем чате, пока меня не было»

• «Проверь, сколько у меня осталось бесплатных расшифровок на этой неделе»

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

Скачивание файлов (по желанию)

По умолчанию выключено. Если включить, ассистент сможет сохранить на компьютер сам файл из сообщения: голосовое (.ogg), кружок или видео (.mp4), фото, документ. Например: «Скачай голосовое от Афанасия». В Telegram при этом ничего не меняется, но инструмент пишет файлы на ваш диск, а установщик заранее одобряет вызовы инструментов сервера, так что подтверждения на каждое скачивание не будет.

Включить: откройте ~/telegram-mcp-ag/config.env и замените TELEGRAM_EXPOSED_TOOLS=read-only на TELEGRAM_EXPOSED_TOOLS=read-only+download_media. Вернуть обратно: снова read-only. Повторный запуск установщика этот выбор не меняет.

• Если приложение сообщает ассистенту папку текущего проекта (так делает Claude Code), файл ложится в подпапку Telegram этого проекта.

• Если не сообщает — в папку Загрузки/Telegram (Downloads/Telegram).

• На macOS при первом скачивании система может спросить, разрешить ли Claude, ChatGPT или терминалу доступ к папке «Загрузки». Разрешите. Если отказать, всё продолжит работать, но файлы будут сохраняться только в папку проекта.

Если ассистент перестал видеть Telegram

Если Telegram-инструменты вдруг перестали работать — скорее всего, сессия для этого устройства была отозвана (например, вручную в приложении Telegram через Настройки → Устройства, или разлогинены сразу все сеансы). Сервер сам распознаёт эту ситуацию и в ответе на любой инструмент сразу называет нужную команду для этой машины — можно просто спросить ассистента ещё раз, он покажет её. Та же команда — на случай, если хотите выполнить её сами, без ассистента (без переустановки клиентов). api_id/api_hash вводить заново не нужно — установщик возьмёт сохранённые при первой установке и сразу покажет QR-код. Спросит он их, только если Telegram их не примет; тогда их можно посмотреть повторно на my.telegram.org/apps:

macOS и Linux:

curl -fsSL https://raw.githubusercontent.com/agroznykh/telegram-mcp-ag/main/install.sh | bash -s -- --relogin

Windows:

$f = "$env:TEMP\telegram-mcp-ag-install.ps1"; iwr 'https://raw.githubusercontent.com/agroznykh/telegram-mcp-ag/main/install.ps1' -OutFile $f; & $f -Relogin

Как удалить

macOS и Linux:

curl -fsSL https://raw.githubusercontent.com/agroznykh/telegram-mcp-ag/main/install.sh | bash -s -- --uninstall

Windows:

$f = "$env:TEMP\telegram-mcp-ag-install.ps1"; iwr 'https://raw.githubusercontent.com/agroznykh/telegram-mcp-ag/main/install.ps1' -OutFile $f; & $f -Uninstall

Обязательно отзовите доступ в приложении Telegram: Настройки → Устройства, найдите устройство с именем вида telegram-mcp-ag (<имя компьютера>) и завершите его сессию. Это самый быстрый и надёжный способ: сработает мгновенно, даже если у вас больше нет доступа к компьютеру, где стоял сервер.

Premium и бесплатная квота на расшифровку

Расшифровка голосовых — это функция самого Telegram, а не этого проекта, и у неё есть ограничение:

• С Telegram Premium — расшифровка без ограничений.

• Без Premium — есть небольшая бесплатная квота (обычно около двух сообщений в неделю, с ограничением по длительности), которая обновляется раз в неделю.

Перед тем как расшифровывать, ассистент сам проверяет остаток квоты — если она закончилась, вы увидите понятное объяснение и дату, когда квота обновится, а не непонятную ошибку Telegram.

Подробнее

• Как устроено «под капотом» (архитектура, апстрим-проект, как именно и где хранятся секреты, почему не поддерживаются веб и мобильные приложения) — в TECHNICAL.md.

• Модель угроз и что делать при подозрении на утечку — в SECURITY.md.

• Для тех, кто хочет доработать код проекта — в CONTRIBUTING.md.

Лицензия

Apache-2.0.