telegram-mcp-ag

Даёт ассистентам Claude и ChatGPT/Codex читать ваш Telegram и расшифровывать голосовые сообщения, видео-кружки и аудио. Только чтение: отправлять сообщения или менять что-либо в вашем аккаунте это не умеет и не будет.

Что умеет

• Читать чаты, папки и контакты.
• Расшифровывать голосовые сообщения, видео-кружки и аудиофайлы/подкасты — можно попросить ассистента пересказать их текстом.
• Пачками: можно попросить «перескажи все голосовые за сегодня» — не придётся просить по одному сообщению.

Не умеет: обычные видео и документы — даже если внутри у них есть звук, Telegram не даёт их транскрибировать.

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

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

Кроме этого, один раз понадобится войти в сам Telegram — по QR-коду: способ покажет либо установщик в терминале, либо ассистент прямо в чате (зависит от варианта, см. ниже). Всё, что вы вводите — api_id, api_hash, вход в Telegram — остаётся только на вашем компьютере и никогда не отправляется в переписку с ассистентом.

Установка

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

Один и тот же установщик: сам находит, что из этого у вас уже стоит на компьютере, и настраивает всё найденное за один запуск (например, если у вас есть и Claude Code, и ChatGPT Desktop — не нужно запускать команду дважды).

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

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

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

iex (irm 'https://raw.githubusercontent.com/agroznykh/telegram-mcp-ag/main/install.ps1')

После установки перезапустите то приложение, которым пользуетесь (если оно уже было открыто) — новые инструменты появятся в новом чате. ChatGPT Desktop доступен на macOS и Windows (официального Linux-приложения у него нет); Claude Code и Codex CLI — на всех трёх ОС.

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

Claude Desktop (и Cowork) — без терминала

Работает на macOS, Windows и Linux.

1. Откройте страницу Releases и скачайте файл с расширением .mcpb.
2. Откройте скачанный файл двойным кликом — Claude Desktop сам предложит его установить.
3. Заполните два поля (api_id и api_hash — см. раздел выше) и подтвердите установку.
4. Ассистент попросит войти в Telegram — покажет QR-код прямо в чате. Откройте Telegram на телефоне, отсканируйте код (Настройки → Устройства → Подключить устройство) — и всё готово. Перезапускать Claude Desktop не нужно — инструменты появятся в том же разговоре. Если этого не произошло, откройте Settings → Extensions и выключите/включите расширение обратно.

Cowork — это раздел внутри того же приложения Claude Desktop, отдельно настраивать его не нужно: всё, что подключено выше, доступно и там.

Если вы уже настроили Claude Desktop через терминальный установщик выше — этот шаг не нужен, всё уже готово.

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

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

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

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

• «Перескажи, что нового в чате „Семья“ за сегодня»
• «Есть голосовые от Артёма за последние два дня? Перескажи текстом»
• «Что писали в рабочем чате, пока меня не было — и включи содержимое кружков»
• «Проверь, сколько у меня осталось бесплатных расшифровок на этой неделе»

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

Установка на вторую машину

Telegram позволяет одной и той же сессии входа работать только на одном устройстве одновременно. Если у вас два компьютера (например, ноутбук и рабочий сервер), на втором нужно просто ещё раз запустить установку — он проведёт отдельный вход, ничего копировать вручную не нужно:

macOS и Linux:

bash install.sh --relogin

Windows (сначала скачайте файл, затем запустите с флагом):

iwr 'https://raw.githubusercontent.com/agroznykh/telegram-mcp-ag/main/install.ps1' -OutFile install.ps1
.\install.ps1 -Relogin

Как удалить

Если ставили через терминал (Claude Code, Codex CLI, ChatGPT Desktop, а также Claude Desktop, если она была настроена тем же установщиком):

macOS и Linux:

bash install.sh --uninstall

Windows (сначала скачайте файл, затем запустите с флагом):

iwr 'https://raw.githubusercontent.com/agroznykh/telegram-mcp-ag/main/install.ps1' -OutFile install.ps1
.\install.ps1 -Uninstall

Если ставили Claude Desktop через .mcpb-бандл: откройте Claude Desktop → Settings → Extensions, найдите telegram-mcp-ag и удалите его там же — так же, как любое другое расширение.

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

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

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

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

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

Подробнее

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

Лицензия

Apache-2.0.