Telegram MCP Server

Телеграм 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 .