# mcp_mtproto

MCP-сервер, який дає Claude доступ до вашого Telegram через протокол MTProto (бібліотека [Telethon](https://github.com/LonamiWebs/Telethon)):
читати історію чатів і каналів, шукати повідомлення, завантажувати фото й файли, дивитися учасників, працювати з ботами.

Сервер працює **лише локально, на вашому комп'ютері**, і входить у Telegram **під вашим особистим акаунтом** (не через бота — інакше історію чужих груп прочитати неможливо). Жодних даних він нікуди не надсилає: усе лишається на вашому диску.

> ⚠️ Файл сесії `data/session.session` дає **повний доступ до вашого Telegram-акаунта**. Нікому його не передавайте, не комітьте в git, не заливайте в хмару. Якщо файл потрапив до чужих рук — відкрийте Telegram → Налаштування → Пристрої й завершіть цей сеанс.

## Що вміє

| Інструмент | Що робить |
|---|---|
| `list_dialogs` | список ваших чатів, каналів і ботів (id, назва, тип) |
| `join_channel` | вступити в публічний канал за `@username` або запрошувальним посиланням |
| `get_history` | історія повідомлень чату за період |
| `search_messages` | пошук за ключовими словами всередині чату |
| `download_media` | завантажити фото й файли з повідомлень у `data/media/<id чату>/` |
| `list_participants` | список учасників (якщо чат його не приховує) |
| `send_to_bot` | надіслати боту повідомлення чи команду й дочекатися відповіді |
| `get_recent_bot_messages` | останні повідомлення бота (щоб побачити кнопки) |
| `click_button` | натиснути inline-кнопку на повідомленні бота |

Усе, крім `join_channel`, `send_to_bot` і `click_button`, лише читає. Ці три дії видимі для інших: акаунт справді вступає в канал або пише боту. Вони виконуються тільки тоді, коли ви (або Claude за вашим проханням) явно їх викликаєте.

## Вимоги

- **Python 3.11 або новіший** (перевірити: `python3 --version` на macOS, `py --version` на Windows).
- Telegram-акаунт з номером телефону.
- Claude Desktop або Claude Code.
- macOS або Windows (на Linux працює так само, як на macOS).

## Крок 1. Отримайте `api_id` і `api_hash` у Telegram

Telegram вимагає, щоб кожен, хто підключається до нього не через офіційний додаток, мав власні ключі. Це безкоштовно й займає кілька хвилин.

1. Відкрийте <https://my.telegram.org/apps> у браузері.
2. Введіть номер телефону вашого Telegram-акаунта (у міжнародному форматі, наприклад `+380...`) і натисніть «Next».
3. Telegram надішле **код входу в сам додаток Telegram** (не SMS) — у чат «Telegram». Введіть його на сайті.
4. Натисніть **API development tools**.
5. Якщо застосунку ще немає, заповніть форму «Create new application»:
   - **App title** — будь-яка назва, наприклад `MCP Telegram`;
   - **Short name** — коротка назва латиницею, 5–32 символи, наприклад `mcptg`;
   - **Platform** — `Desktop`;
   - **Description** — необов'язково.
6. Натисніть «Create application». На сторінці з'являться **App api_id** (число) та **App api_hash** (рядок із 32 символів). Збережіть їх — вони знадобляться на кроці 4.

Поради:
- `api_hash` — секрет. Не публікуйте його, не надсилайте в чат і не комітьте.
- Якщо сайт показує помилку («ERROR») при створенні застосунку, спробуйте ще раз пізніше, з іншого браузера, а також без VPN/проксі — це відома примха сайту Telegram.
- Використовуйте той номер, яким будете логінитися в сервері на кроці 5.

## Крок 2. Завантажте код

```
git clone https://github.com/vredin/mcp_mtproto.git
cd mcp_mtproto
```

Не маєте git — натисніть на GitHub «Code → Download ZIP», розпакуйте архів і відкрийте термінал у цій папці.

## Крок 3. Створіть віртуальне середовище й встановіть залежності

### macOS (Terminal)

```
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### Windows (PowerShell)

```
py -3 -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

Якщо PowerShell відповідає, що виконання скриптів вимкнене, або виконайте один раз
`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`, або скористайтеся командним рядком (cmd) і `.venv\Scripts\activate.bat`. Також можна взагалі не активувати середовище, а викликати Python напряму: `.venv\Scripts\python.exe ...`.

## Крок 4. Пропишіть ключі в `.env`

### macOS

```
cp .env.example .env
open -e .env
```

### Windows (PowerShell)

```
copy .env.example .env
notepad .env
```

Впишіть значення з кроку 1 (без пробілів і лапок):

```
TELEGRAM_API_ID=1234567
TELEGRAM_API_HASH=0123456789abcdef0123456789abcdef
```

Файл `.env` уже в `.gitignore` і не потрапить у репозиторій.

## Крок 5. Один раз увійдіть у Telegram

Це інтерактивний крок, його робить людина в терміналі.

### macOS

```
.venv/bin/python -m app.auth
```

### Windows

```
.venv\Scripts\python.exe -m app.auth
```

Програма запитає:
1. **номер телефону** (у форматі `+380...`);
2. **код** — він прийде в додаток Telegram на іншому вашому пристрої (або SMS, якщо додатка немає);
3. **пароль двоетапної перевірки** (2FA), якщо ви його вмикали.

Після успіху з'явиться повідомлення «Вход выполнен: …» і файл `data/session.session`. Далі сервер входить сам, без запитань. Цей крок повторювати не треба, поки ви не завершите сеанс у Telegram.

## Крок 6. Перевірте, що сервер запускається

macOS:

```
.venv/bin/python -m app.server
```

Windows:

```
.venv\Scripts\python.exe -m app.server
```

Сервер нічого не виводить і чекає запитів (це нормально, він говорить з клієнтом через stdin/stdout). Зупиніть його `Ctrl+C`.

## Крок 7. Підключіть до Claude

- **Claude Desktop** — окрема інструкція: [docs/CLAUDE_DESKTOP.md](docs/CLAUDE_DESKTOP.md).
- **Claude Code** — команда нижче, де шлях має бути повним шляхом до вашої папки.

  macOS:
  ```
  claude mcp add mcp-mtproto -e PYTHONPATH=/Users/ВАШ_КОРИСТУВАЧ/mcp_mtproto -- /Users/ВАШ_КОРИСТУВАЧ/mcp_mtproto/.venv/bin/python -m app.server
  ```
  Windows (PowerShell):
  ```
  claude mcp add mcp-mtproto -e PYTHONPATH=C:\Users\ВАШ_КОРИСТУВАЧ\mcp_mtproto -- C:\Users\ВАШ_КОРИСТУВАЧ\mcp_mtproto\.venv\Scripts\python.exe -m app.server
  ```

## Як користуватися

Просто пишіть Claude звичайною мовою. Приклади:

- «Покажи мої чати» → `list_dialogs`.
- «Знайди в чаті про оренду в Софії згадки про "Лозенець" за останній тиждень» → `search_messages`.
- «Завантаж фото з повідомлень 15098 і 15101 у чаті про оренду» → `download_media`.

Важливо: **номер повідомлення унікальний лише в межах одного чату**, тому завжди називайте чат. У інструмент можна передати id чату, `@username` або посилання `t.me/...`. Якщо ви називаєте чат словами, Claude сам знайде його id через `list_dialogs` (чат має бути у вашому списку; за замовчуванням повертаються перші 50, тож для старого чату Claude може попросити збільшити `limit`).

Завантажені файли лежать у `data/media/<id чату>/<номер повідомлення>.<розширення>`. Повторний запит бере файл із диска. Файли не видаляються автоматично.

## Відмінності Windows і macOS — коротко

| | macOS | Windows |
|---|---|---|
| Python у середовищі | `.venv/bin/python` | `.venv\Scripts\python.exe` |
| Активація середовища | `source .venv/bin/activate` | `.venv\Scripts\Activate.ps1` (PowerShell) |
| Створення середовища | `python3 -m venv .venv` | `py -3 -m venv .venv` |
| Копіювання `.env` | `cp` | `copy` |
| Конфіг Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | `%APPDATA%\Claude\claude_desktop_config.json` |
| Шляхи в JSON | звичайні `/` | `\\` (подвійні) або `/` |
| Повний вихід із Claude Desktop | `Cmd+Q` | значок у системному треї → Quit |
| Права на файл сесії | `chmod 600` виставляється автоматично | NTFS-права за замовчуванням: файл доступний лише вашому користувачу, якщо ви не змінювали права папки |

## Безпека й обмеження

- Секрети (`.env`, `data/`) не потрапляють у git, але зберігаються на диску у відкритому вигляді. Захистіть комп'ютер паролем і шифруванням диска.
- Це автоматизація **особистого акаунта**. Telegram обмежує частоту запитів: за надто частих запитів API відповідає `FloodWait`, і сервер сам чекає й повторює спробу (до 3 разів). Масові вступи в канали, великі вивантаження й розсилки можуть призвести до тимчасового, а за зловживання — і постійного блокування акаунта. Користуйтеся помірно й дотримуйтесь [Умов користування Telegram API](https://core.telegram.org/api/terms).
- Історія чужих чатів і списки учасників — це персональні дані інших людей. Збирайте й зберігайте їх лише в межах закону (зокрема GDPR) і правил самих чатів.
- Не використовуйте цей сервер для спаму, збору даних без підстав чи будь-яких дій, які порушують права інших.

## Усунення проблем

| Симптом | Що робити |
|---|---|
| «Сессия не найдена» | Виконайте крок 5 (`python -m app.auth`) із цієї самої папки. |
| «Сессия протухла или отозвана» | Завершили сеанс у Telegram — повторіть крок 5; перед цим видаліть `data/session.session`. |
| «TELEGRAM_API_ID / TELEGRAM_API_HASH не заданы» | Перевірте `.env` (крок 4): файл має лежати в корені проєкту й називатися саме `.env`. |
| Код не приходить | Дивіться в самому додатку Telegram (чат «Telegram»), а не в SMS. |
| `FloodWait` | Зачекайте вказаний час, зменшіть `limit`, не робіть багато запитів поспіль. |
| `ModuleNotFoundError: app` | Сервер запущено не з кореня проєкту й без `PYTHONPATH`. Дотримуйтесь конфігу з docs/CLAUDE_DESKTOP.md. |

## Ліцензія

MIT, див. [LICENSE](LICENSE). Функція `retry_on_flood` взята з [TGgrabber](https://github.com/Magerko/TGgrabber) (MIT), див. [NOTICE](NOTICE).