Telegram MCP Server

MCP-сервер для извлечения истории чатов Telegram, включая текстовые сообщения, фото и документы. Использует GramJS (MTProto userbot) для полного доступа к личным чатам.

Требования

• Node.js 18+
• Telegram API credentials (my.telegram.org)

Установка

npm install
cp .env.example .env
# Заполнить TELEGRAM_API_ID и TELEGRAM_API_HASH в .env

Первый запуск — аутентификация

npm run auth

Введи номер телефона → код из Telegram → пароль 2FA (если есть). Сессия сохранится в telegram.session.

Сборка и запуск

npm run build
npm start

Транспорты

Сервер поддерживает два режима работы, выбираемых переменной TRANSPORT:

Переменная	Значение	Описание
TRANSPORT=stdio	по умолчанию	Локальный запуск через stdin/stdout, авторизация не нужна (процесс изолирован)
TRANSPORT=http	сетевой режим	HTTP-сервер на порту PORT (по умолчанию 3000), требуется AUTH_TOKEN

stdio (по умолчанию)

Сервер общается с клиентом через stdin/stdout. Безопасность обеспечивается изоляцией процесса — доступ имеет только тот, кто его запустил.

HTTP с Bearer token авторизацией

Для сетевого доступа (например, сервер на удалённой машине). Каждый запрос должен содержать заголовок:

Authorization: Bearer <ваш_токен>

Без валидного токена сервер вернёт 401 Unauthorized.

Сгенерировать токен:

node -e "console.log(crypto.randomUUID())"

Настроить в .env:

TRANSPORT=http
PORT=3000
AUTH_TOKEN=ваш-секретный-токен

Подключение к Claude Code / Claude Desktop

Claude Code — stdio (локально)

claude mcp add telegram-mcp -- node /path/to/telegram-mcp-server/dist/index.js

Claude Code — HTTP (удалённый сервер)

claude mcp add telegram-mcp \
  --transport http \
  --url http://your-server:3000/mcp \
  --header "Authorization: Bearer ваш-секретный-токен"

Claude Desktop (config)

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/path/to/telegram-mcp-server/dist/index.js"],
      "env": {
        "TELEGRAM_API_ID": "your_id",
        "TELEGRAM_API_HASH": "your_hash",
        "TELEGRAM_SESSION_PATH": "/path/to/telegram.session",
        "DATA_DIR": "/path/to/data"
      }
    }
  }
}

Docker

Сборка

docker build -t telegram-mcp .

Запуск — stdio

docker run --rm -i \
  -e TELEGRAM_API_ID=12345 \
  -e TELEGRAM_API_HASH=abc123 \
  -v ./telegram.session:/app/telegram.session \
  -v ./data:/app/data \
  telegram-mcp

Запуск — HTTP с авторизацией

docker run -d \
  -e TRANSPORT=http \
  -e AUTH_TOKEN=ваш-секретный-токен \
  -e TELEGRAM_API_ID=12345 \
  -e TELEGRAM_API_HASH=abc123 \
  -v ./telegram.session:/app/telegram.session \
  -v ./data:/app/data \
  -p 3000:3000 \
  telegram-mcp

Инструменты (Tools)

Tool	Описание
telegram_list_chats	Список всех чатов
telegram_find_chat	Поиск чата по имени/username/ID
telegram_get_history	Получить сообщения (без скачивания медиа)
telegram_sync_chat	Основной — полная синхронизация чата с медиа
telegram_download_media	Скачать медиа из конкретного сообщения
telegram_sync_status	Статус последней синхронизации
telegram_list_media	Список скачанных медиафайлов

Типичный workflow

1. telegram_find_chat("Мама")           → получаем chat_id
2. telegram_sync_chat(chat_id)          → скачиваем всё
3. telegram_list_media(chat_id, "photo") → список фотографий
4. Загружаем файлы из data/raw/{chat_id}/media/ в Claude для анализа

Через 2 недели:

telegram_sync_chat(chat_id)  → скачает только новые сообщения

Структура данных

data/
└── raw/
    └── {chat_id}/
        ├── messages.json      # все сообщения
        ├── media_index.json   # индекс медиафайлов
        ├── sync_state.json    # состояние синхронизации
        └── media/             # скачанные файлы
            ├── photo_123.jpg
            ├── doc_456.pdf
            └── ...

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

• Сессия Telegram хранится в файле (добавлен в .gitignore)
• API credentials в .env (добавлен в .gitignore)
• HTTP транспорт защищён Bearer token авторизацией
• Данные хранятся только локально