mcp-telegram

Локальный MCP-сервер, который подключает Claude (Claude Code / Claude Desktop) к вашему личному аккаунту Telegram через MTProto (библиотека gramjs).

Это не Bot API — Claude работает от имени вашего пользователя: видит ваши чаты, диалоги, контакты, может читать и отправлять сообщения, скачивать файлы и т.д.

🔒 Шифрование и приватность

• MTProto. Сервер общается с Telegram напрямую по протоколу MTProto — том же, что используют официальные приложения Telegram. Трафик между вашим компьютером и серверами Telegram зашифрован; для Telegram это обычный вход устройства.
• Всё локально. api_id/api_hash, файл сессии и сами сообщения остаются только на вашем компьютере (~/.mcp-telegram/, права 600). Никуда не загружаются, кроме серверов самого Telegram. Claude читает их через этот локальный процесс — ничего не уходит в Anthropic или куда-либо ещё.

⚠️ Важно: не запускайте через npx mcp-telegram. В npm-реестре есть другой, посторонний пакет с таким же именем (mcp-telegram от beautyfree) — npx скачает именно его. Этот, локальный, сервер запускается напрямую через node (см. ниже).

Возможности

• 🖥 Локальная веб-панель (npm start) — вход/выход/подключение к Claude по красоте
• 🔐 Авторизация по номеру телефона или QR-коду, поддержка 2FA-пароля
• 💾 Сессия сохраняется — повторный вход не требуется
• 🛠 11 инструментов (tools) и 4 ресурса (resources) для Claude
• ⏳ Автоматическая обработка FLOOD_WAIT (ограничения Telegram)
• 🧹 Все ответы — чистый структурированный JSON, а не сырые объекты gramjs

Требования

• Node.js ≥ 18
• api_id и api_hash с my.telegram.org (бесплатно, см. ниже)

Быстрый старт

Веб-панель ⭐ (проще всего)

npm install
npm start

Откроется локальная страница http://127.0.0.1:8765 (только на вашем компьютере), где можно:

• ввести api_id/api_hash;
• войти по QR (картинкой) или по номеру (код → 2FA, неверный пароль можно ввести заново);
• одной кнопкой добавить сервер в Claude Code;
• посмотреть примеры запросов к Claude;
• выйти из аккаунта (с отзывом сессии на стороне Telegram);
• удалить ключи api_id/api_hash и сбросить всё к первому запуску.

Дизайн чистый, с тёмной темой по системной настройке. После входа просто перезапустите Claude Code.

npm run quick_start — то же самое, просто открывает панель (алиас ui).

Вход через терминал (если без браузера)

1. Авторизация (один раз):

npm run auth

При первом запуске сервер:

1. Покажет, как всё устроено (MTProto + локальность).
2. Спросит api_id и api_hash (если их ещё нет) и объяснит, где их взять.
3. Предложит войти по QR-коду или по номеру телефона (телефон не требует второго устройства — код придёт по SMS/в Telegram). Неверный 2FA-пароль можно ввести заново (до 3 попыток).
4. Сохранит сессию в ~/.mcp-telegram/session.json и автоматически добавит сервер в Claude Code.

2. Добавить сервер в Claude вручную (если нужно отдельно):

npm run add_mcp

Эта команда выполняет claude mcp add --scope user telegram -- node "<путь>/dist/index.js". Если CLI claude не найден, она напечатает готовый JSON-сниппет для ручной вставки:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["C:\\Other\\MCPTelegram\\dist\\index.js"]
    }
  }
}

После добавления перезапустите Claude Code и наберите /mcp — там должен появиться telegram. Claude сам запустит сервер (режим MCP на stdio), отдельно стартовать ничего не нужно.

Где взять api_id / api_hash

1. Откройте https://my.telegram.org и войдите по номеру телефона.
2. Перейдите в API development tools.
3. Создайте приложение (любые название и short name).
4. Скопируйте api_id (число) и api_hash (длинная строка).

Их вводят один раз — дальше они хранятся в ~/.mcp-telegram/config.json.

Инструменты (MCP tools)

| Инструмент | Параметры | Описание | |---|---|---| | get_dialogs | limit, offset | Список чатов/диалогов | | get_messages | chat_id, limit | История сообщений из чата | | search_messages | query, chat_id?, limit | Поиск по сообщениям (в чате или глобально) | | get_unread | max_chats, max_messages_per_chat | Все непрочитанные сообщения | | send_message | chat_id, text | Отправить сообщение | | reply_to_message | chat_id, message_id, text | Ответить на конкретное сообщение | | forward_message | from_chat, to_chat, message_id | Переслать сообщение | | download_file | chat_id, message_id, include_base64? | Скачать файл/фото (путь + опц. base64) | | send_file | chat_id, file_path, caption? | Отправить файл | | get_contacts | — | Список контактов | | get_chat_members | chat_id, limit | Участники группы/канала |

chat_id принимает числовой id, @username или ссылку t.me/....

Ресурсы (MCP resources)

| URI | Описание | |---|---| | telegram://dialogs | Все диалоги | | telegram://chat/{id} | Конкретный чат + последние сообщения | | telegram://unread | Непрочитанные сообщения | | telegram://me | Профиль текущего пользователя |

Сценарии использования

Что можно просить у Claude после подключения:

• «Суммаризируй последние 50 сообщений из чата с Ваней»
• «Ответь Маше, что я буду в 19:00»
• «Покажи все непрочитанные и расставь приоритеты»
• «Разошли в эти 5 чатов: [текст]»
• «Найди все сообщения, где упоминается договор»
• «Составь дайджест канала @somechannel за последнюю неделю»

Команды CLI

npm start                        # ⭐ веб-панель: вход/выход/подключение к Claude/удаление ключей
npm run quick_start              # то же самое — открыть веб-панель (алиас)
npm run auth                     # вход через терминал (телефон/QR) + авто-добавление в Claude
npm run add_mcp                  # только зарегистрировать сервер в Claude Code
npm run logout                   # выйти из Telegram и удалить сессию
npm run delete_key               # удалить api_id/api_hash и выйти (полный сброс)
npm run status                   # показать, есть ли валидная сессия

# то же напрямую через node:
node dist/index.js               # в терминале — настройка/проверка; под Claude — запуск сервера
node dist/index.js ui            # веб-панель управления
node dist/index.js auth          # вход через терминал + добавление в Claude
node dist/index.js add_mcp       # добавить сервер в Claude Code
node dist/index.js status        # есть ли валидная сессия
node dist/index.js logout        # выйти из Telegram + удалить сессию
node dist/index.js delete_key    # удалить ключи api_id/api_hash + выйти
node dist/index.js config        # вывести JSON-сниппет для Claude Code
node dist/index.js serve         # принудительно режим MCP-сервера (stdio)
node dist/index.js help          # справка

Безопасность и хранение данных

Всё хранится локально, с правами 600 там, где ОС это поддерживает:

~/.mcp-telegram/
├── config.json     # api_id, api_hash
├── session.json    # строка сессии gramjs (эквивалент входа в аккаунт)
└── downloads/      # скачанные через download_file файлы

• Эти данные никуда не загружаются, кроме официальных серверов Telegram через MTProto.
• session.json равноценен входу в ваш аккаунт — не публикуйте его.
• Чтобы выйти: node dist/index.js logout (и при желании удалите устройство в Telegram → Settings → Devices).

Обработка ошибок

• Протухшая сессия. Инструменты вернут понятную ошибку с подсказкой npm run auth; при запуске сервера проверка происходит сразу.
• FLOOD_WAIT. Короткие задержки gramjs выжидает сам; более длинные обрабатывает встроенный повтор (до 5 минут), после чего запрос повторяется.

Разработка

npm install
npm run build      # компиляция TypeScript -> dist/
npm run dev        # сборка в watch-режиме
node dist/index.js status

Структура:

src/
├── index.ts             # точка входа: CLI-команды + запуск MCP-сервера на stdio
├── auth.ts              # CLI-авторизация (номер + QR), баннер про MTProto/локальность
├── web.ts               # локальная веб-панель (HTTP API + мост к логину gramjs)
├── web-page.ts          # HTML/CSS/JS страницы веб-панели
├── client.ts            # обёртка над gramjs + сериализация в JSON + logout
├── tools.ts             # все MCP tools
├── resources.ts         # все MCP resources
├── storage.ts           # хранение сессии и конфига (~/.mcp-telegram)
├── claude.ts            # авто-регистрация сервера в Claude Code (claude mcp add)
├── notice.ts            # английские заметки про MTProto/локальность для терминала
└── suppress-warnings.ts # глушит шумный localStorage-варнинг Node

Лицензия

MIT