telegram-mcp

Сервер протокола Model Context Protocol (MCP) для взаимодействия с Telegram с использованием mtcute.

Возможности

• Отправка текстовых сообщений в чаты

• Ожидание входящих сообщений в определенных чатах

• Чтение сообщений из чатов

• Поиск сообщений

• Список и получение информации о диалогах (чатах)

• Получение последних сообщений из всех чатов

• Установка и просмотр ID эмодзи-статусов для аккаунтов и каналов

Related MCP server: io.github.daedalus/mcp-telegram-bot

Настройка

Установка

Вариант 1: Загрузка готового бинарного файла

Загрузите последний релиз для вашей платформы со страницы релизов:

• macOS (Apple Silicon): telegram-mcp-darwin-arm64.tar.gz

• macOS (Intel): telegram-mcp-darwin-x64.tar.gz

• Linux: telegram-mcp-linux-x64.tar.gz

• Windows: telegram-mcp-win-x64.exe.zip

Распакуйте архив и сделайте файл исполняемым (для Unix-систем):

tar -xzf telegram-mcp-*.tar.gz
chmod +x telegram-mcp

Вариант 2: Сборка из исходного кода

1. Клонируйте репозиторий и установите зависимости:

git clone git@github.com:zhigang1992/telegram-mcp.git
cd telegram-mcp
bun install

2. Соберите исполняемый файл:

bun run build

Первоначальная настройка (только один раз)

1. Получите учетные данные Telegram API на сайте https://my.telegram.org

2. Запустите первоначальную настройку для аутентификации в Telegram:

export API_ID=your_api_id
export API_HASH=your_api_hash
./telegram-mcp

Сервер:

• Попросит вас ввести номер телефона

• Отправит код подтверждения через Telegram

• Запросит код подтверждения

• Отобразит абсолютный путь к хранилищу (он понадобится для конфигурации MCP)

3. Запишите путь к хранилищу, отображенный в выводе. Он будет выглядеть примерно так:

Storage path: /Users/username/telegram-mcp/bot-data/session

Использование

В качестве MCP-сервера

Добавьте в конфигурацию Claude Desktop, используя путь к хранилищу из первоначальной настройки:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/telegram-mcp",
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash",
        "TELEGRAM_STORAGE_PATH": "/absolute/path/from/initial/setup"
      }
    }
  }
}

Важно: TELEGRAM_STORAGE_PATH должен быть абсолютным путем, показанным во время первоначальной настройки. Это гарантирует, что MCP-сервер будет использовать аутентифицированную сессию.

Доступные инструменты

Инструменты для сообщений

• messages_sendText - Отправка текстового сообщения в чат

  • chatId (обязательно): ID чата/пользователя или имя пользователя

  • text (обязательно): Текст сообщения для отправки

  • replyToMessageId: Опциональный ID сообщения для ответа

• messages_getHistory - Получение истории сообщений из чата

  • chatId (обязательно): ID чата/пользователя или имя пользователя

  • limit: Количество сообщений (по умолчанию: 100, макс: 100)

  • offsetId: ID сообщения для пагинации

• messages_search - Поиск сообщений

  • query (обязательно): Поисковый запрос

  • chatId: Конкретный чат для поиска (опционально)

  • limit: Количество результатов (по умолчанию: 50)

• messages_getRecent - Получение последних сообщений из всех чатов

  • limit: Количество чатов (по умолчанию: 10)

  • messagesPerChat: Сообщений на чат (по умолчанию: 10)

Интерактивные инструменты

• wait_for_reply - Ожидание следующего сообщения в чате

  • chatId (обязательно): ID чата/пользователя или имя пользователя, от которого ожидается сообщение

  • timeoutSeconds: Тайм-аут в секундах (по умолчанию: 60, макс: 300)

Инструменты статуса

• status_getCurrent - Получение текущего эмодзи-статуса для участника

  • peerId: Целевой участник, по умолчанию self

• status_setEmoji - Установка или очистка эмодзи-статуса

  • peerId: Целевой участник, по умолчанию self

  • emojiId: ID документа пользовательского эмодзи, обязательно, если clear=false

  • isCollectible: Установите true, если emojiId является ID коллекционного предмета

  • until: Опциональная метка времени ISO-8601 или строка метки времени Unix

  • clear: Очистить текущий статус вместо установки нового

• status_listAvailable - Список доступных ID эмодзи-статусов по умолчанию

  • scope: self или channel (по умолчанию: self)

  • limit: Максимальное количество ID для возврата (по умолчанию: 100)

• status_listCollectibles - Список принадлежащих пользователю коллекционных ID, которые можно использовать в качестве эмодзи-статуса

  • owner: Участник для проверки, по умолчанию self

  • limit: Максимальное количество коллекционных предметов для возврата (по умолчанию: 100)

Инструменты диалогов

• dialogs_list - Список всех диалогов

  • limit: Максимальное количество диалогов (по умолчанию: 50)

  • filter: Опции фильтрации (onlyUsers, onlyGroups, onlyChannels)

• dialogs_getInfo - Получение подробной информации о диалоге

  • chatId (обязательно): ID чата/пользователя или имя пользователя

Разработка

Запуск в режиме разработки:

bun run dev

Сервер хранит данные сессии в директории bot-data/.