# telegram-mcp-ag

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

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

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

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

1. Откройте в браузере [my.telegram.org](https://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** (строка из букв и цифр). Их и нужно скопировать и вставить
   туда, где просит установщик.

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

## Установка

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

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

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

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

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

```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 (режим Cowork) (обязательный шаг)

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

**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` в
Загрузках. Скилл появится в списке.

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

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

А также режим **Chat** в десктопных приложениях — ни **Claude Chat (desktop)**,
ни **ChatGPT Chat (desktop)**: на данный момент MCP-инструменты в нём не
подключаются, работает только режим Cowork/Work соответственно.

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

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

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

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

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

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

**macOS и Linux:**

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

**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 -Relogin
```

## Как удалить

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

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 -Uninstall
```

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

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

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

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

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

## Подробнее

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

## Лицензия

Apache-2.0.