Телеграм MCP-сервер

MCP-сервер, позволяющий помощникам ИИ (например, Клоду) взаимодействовать с вашим аккаунтом Telegram с помощью API клиента пользователя (не API бота). Создан с помощью @mtproto/core и фреймворка FastMCP .

Функции

Инструменты

• listChannels

  • Выводит список доступных Telegram-каналов/чатов, доступных для учетной записи, на основе кэша сервера.

  • Параметры:

    • limit (число, необязательно): максимальное количество каналов для возврата (по умолчанию: 50).

  • Вывод: список каналов/чатов с их идентификатором, названием, типом и хешем доступа (если применимо).

• searchChannels

  • Поиск кэшированных каналов/чатов по ключевым словам в их названиях.

  • Параметры:

    • keywords (строка): Ключевые слова для поиска в названиях каналов.

    • limit (число, необязательно): максимальное количество возвращаемых результатов (по умолчанию: 100).

  • Вывод: список соответствующих каналов/чатов.

• getChannelMessages

  • Извлекает последние сообщения из определенного канала/чата, используя его идентификатор.

  • Параметры:

    • channelId (число): числовой идентификатор канала/чата (полученный из listChannels или searchChannels ).

    • limit (число, необязательно): максимальное количество возвращаемых сообщений (по умолчанию: 100).

    • filterPattern (строка, необязательно): регулярное выражение, совместимое с JavaScript, для фильтрации сообщений по их текстовому содержимому.

  • Вывод: список сообщений, содержащих идентификатор, дату, текст и идентификатор отправителя.

Предпосылки

1. Node.js: рекомендуется версия 18 или более поздняя.

2. Аккаунт в Telegram:

   • Вам необходим активный аккаунт Telegram.

   • В вашей учетной записи должна быть включена двухэтапная аутентификация (2FA) (Настройки → Конфиденциальность и безопасность → Двухэтапная аутентификация).

3. Учетные данные API Telegram:

   • Получите api_id и api_hash создав новое приложение по адресу https://core.telegram.org/api/obtaining_api_id .

Установка

1. Клонируйте этот репозиторий:

   git clone https://github.com/your-username/telegram-mcp-server.git # Replace with your repo URL cd telegram-mcp-server

2. Установите зависимости:

   npm install

Конфигурация

Необходимо настроить две отдельные конфигурации:

1. Конфигурация сервера MCP:

   Настройте сервер Telegram MCP с помощью переменных среды (в файле .env или непосредственно в вашей среде):

   TELEGRAM_API_ID=YOUR_API_ID TELEGRAM_API_HASH=YOUR_API_HASH TELEGRAM_PHONE_NUMBER=YOUR_PHONE_NUMBER_WITH_COUNTRY_CODE # e.g., +15551234567

   Замените значения заполнителей своими фактическими учетными данными.

2. Конфигурация клиента MCP:

   Настройте клиентское программное обеспечение (Claude Desktop, Cursor и т. д.) для подключения к серверу MCP, изменив их файлы конфигурации:

   { "mcpServers": { "telegram": { "url": "http://localhost:8080/sse", "disabled": false, "timeout": 30 } } }

   Для Claude Desktop файл конфигурации находится по адресу:

   • В macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • В Windows: %APPDATA%/Claude/claude_desktop_config.json

   Важно: перезапустите клиент MCP, чтобы изменения вступили в силу.

Запуск сервера

1. Первоначальный вход (важный первый шаг): при первом запуске сервера (или если ваш сеанс истек/недействителен), он должен пройти аутентификацию в Telegram. Запустите его прямо из терминала:

   npm start

   • Сервер будет использовать учетные данные из вашего файла .env .

   • В терминале вам будет предложено ввести код входа, отправленный на ваш аккаунт Telegram, и пароль 2FA, если требуется.

   • При успешном входе будет создан файл сеанса ( ./data/session.json ). Этот файл позволяет серверу в будущем входить в систему автоматически, не требуя кодов/паролей.

   • Сервер также попытается создать или загрузить кэш ваших чатов ( ./data/dialog_cache.json ). Это может занять некоторое время при первом запуске, особенно при большом количестве чатов. Последующие запуски будут быстрее, если кэш существует.

2. Обычная работа: Вам необходимо запустить сервер вручную, выполнив команду npm start в каталоге проекта.

   После запуска сервера ваш клиент MCP (например, Claude Desktop) подключится к нему по URL-адресу, указанному в его конфигурации (по умолчанию http://localhost:8080/sse ).

Поиск неисправностей

• Запросы на вход: Если сервер продолжает запрашивать коды входа/пароли при запуске клиентом MCP, убедитесь, что файл data/session.json существует и действителен. Возможно, вам придется запустить npm start вручную один раз, чтобы обновить сеанс. Также проверьте, что права доступа к файлу позволяют пользователю, запустившему клиент MCP, читать/писать каталог data .

• Проблемы с кэшем: Если каналы кажутся устаревшими или отсутствуют, вы можете удалить ./data/dialog_cache.json и перезапустить сервер (запустить npm start вручную), чтобы принудительно выполнить полное обновление. Это может занять некоторое время.

• Не удается найти модуль: убедитесь, что вы запустили npm install в каталоге проекта. Если клиент MCP запускает сервер, убедитесь, что рабочий каталог установлен правильно или используйте абсолютные пути.

• Другие проблемы: Если у вас возникнут какие-либо другие проблемы, смело сообщайте о них в этом репозитории сервера .

Библиотека клиента Telegram

Этот репозиторий также содержит базовую библиотеку telegram-client.js используемую сервером MCP. Подробности об использовании библиотеки напрямую (например, для пользовательских скриптов) см. в LIBRARY.md .

Лицензия

Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE .