Telegram MCP

MCP-сервер для личного Telegram. ИИ-агент — Claude Code, Codex и другие MCP-клиенты — находит чаты, читает и ищет переписку, скачивает вложения. Сообщения и файлы отправляет только с confirm: true, по прямой просьбе.

Отдельная сессия MTProto (GramJS), stdio, без браузера и без tdata.

Документация: https://sonicxboy.dev/products/telegram-mcp/

Установка

Нужен Node.js (проверено на 22).

git clone https://github.com/vixkosla/telegram-mcp.git
cd telegram-mcp
npm ci

1. На https://my.telegram.org → API development tools создайте приложение и запишите ключи в ~/.config/telegram-mcp/config.json (права 0600):

   {"apiId": 123456, "apiHash": "32-символьный hex"}
   

   Вместо файла можно задать TELEGRAM_API_ID и TELEGRAM_API_HASH, другой путь к файлу — через TELEGRAM_MCP_CONFIG. Если MTProto не доходит до Telegram, добавьте "proxy": "socks5://127.0.0.1:1080".

2. Войдите: node server.mjs login — телефон, код из Telegram, при необходимости облачный пароль. Сессия сохранится в session.txt рядом с сервером (права 0600). Не копируйте и не публикуйте этот файл.

3. Подключите к клиенту.

   Claude Code:

   claude mcp add telegram -- node /path/to/telegram-mcp/server.mjs
   

   Codex (~/.codex/config.toml):

   [mcp_servers.telegram]
   command = "node"
   args = ["/path/to/telegram-mcp/server.mjs"]
   startup_timeout_sec = 20
   

   Cursor, Claude Desktop и другие:

   {"mcpServers": {"telegram": {"command": "node", "args": ["/path/to/telegram-mcp/server.mjs"]}}}
   

4. Попросите агента вызвать status.

Инструменты

Инструмент	Что делает
status	Есть ли вход и под каким аккаунтом
list_dialogs	Последние чаты, поиск по имени и @username, архив
get_messages	История чата постранично, без отметки о прочтении
search_messages	Поиск по всем чатам или внутри одного
download_media	Фото и документы до 20 сообщений, до 50 МБ на файл, в downloads/
send_message	Текст до 4096 символов, confirm: true
send_file	Локальный файл до 50 МБ по абсолютному пути, confirm: true
login_send_code, login_sign_in	Вход по коду и облачному паролю
logout	Закрывает только эту сессию, confirm: true

peer — id из list_dialogs, @username или title:Название.

Безопасность

• Отдельное устройство в списке сессий Telegram; logout не трогает другие.
• Отправка и выход без confirm: true не выполняются.
• Текст сообщений и содержимое файлов — чужой ввод: сервер просит агента не выполнять инструкции из них.
• session.txt, pending.json и скачанные файлы пишутся с правами 0600.
• Длинные токены вырезаются из ошибок, телефон показывается последними четырьмя цифрами.
• send_file отправляет любой читаемый файл по абсолютному пути. Разрешайте отправку только тех файлов, которые проверили сами.

English

MCP server that connects a personal Telegram account to AI agents (Claude Code, Codex, any stdio MCP client): list chats, read and search history without marking it read, download media, and send messages or files only with confirm: true. Uses its own MTProto session via GramJS. Setup: create an app at my.telegram.org, put apiId/apiHash in ~/.config/telegram-mcp/config.json, run node server.mjs login, then add node /path/to/server.mjs to your MCP client.

Проверка изменений

После npm ci запустите npm test. Тесты вызывают MCP-сервер через stdio с подставным Telegram-клиентом и временными файлами. Ключи и вход в Telegram не нужны; тесты не обращаются к сети или рабочей сессии.

Лицензия

MIT © SonicXBoy