mcp_mtproto

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

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

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

Що вміє

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

Related MCP server: Telegram MCP Server

Вимоги

• 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.

• 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 — коротко

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

• Секрети (.env, data/) не потрапляють у git, але зберігаються на диску у відкритому вигляді. Захистіть комп'ютер паролем і шифруванням диска.

• Це автоматизація особистого акаунта. Telegram обмежує частоту запитів: за надто частих запитів API відповідає FloodWait, і сервер сам чекає й повторює спробу (до 3 разів). Масові вступи в канали, великі вивантаження й розсилки можуть призвести до тимчасового, а за зловживання — і постійного блокування акаунта. Користуйтеся помірно й дотримуйтесь Умов користування Telegram API.

• Історія чужих чатів і списки учасників — це персональні дані інших людей. Збирайте й зберігайте їх лише в межах закону (зокрема GDPR) і правил самих чатів.

• Не використовуйте цей сервер для спаму, збору даних без підстав чи будь-яких дій, які порушують права інших.

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

Ліцензія

MIT, див. LICENSE. Функція retry_on_flood взята з TGgrabber (MIT), див. NOTICE.