mcp-telegram

MCP-сервер для Telegram — позвольте ИИ-ассистентам взаимодействовать с вашим аккаунтом Telegram

Возможности

• Управление чатами: список, поиск, включение/выключение уведомлений

• Сообщения: чтение, поиск, просмотр контекста, отправка, черновики, отложенная отправка, разрешение ссылок и резервное копирование сообщений

• ИИ-суммаризация: краткое изложение переписки в чатах с использованием различных LLM-провайдеров

• Безопасность: сессия хранится в macOS Keychain (на Linux/Windows используется файловое хранилище)

Установка

go install github.com/tolmachov/mcp-telegram@latest

Или соберите из исходного кода:

git clone https://github.com/tolmachov/mcp-telegram.git
cd mcp-telegram
make

Настройка

1. Получите учетные данные Telegram API

1. Перейдите на my.telegram.org/apps

2. Создайте приложение

3. Скопируйте api_id и api_hash

2. Настройте окружение

Сохраните учетные данные (macOS Keychain; обычный JSON-файл по пути ~/.local/state/mcp-telegram/config.json с правами 0600 на Linux/Windows):

mcp-telegram config set TELEGRAM_API_ID 123456789
mcp-telegram config set TELEGRAM_API_HASH abcd1234efgh5678

Или используйте файл .env:

cp .env.example .env
# Edit .env with your credentials

3. Войдите в Telegram

mcp-telegram login --phone +1234567890

Вас попросят ввести код подтверждения, отправленный в ваш Telegram.

4. Настройте MCP-клиент

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "telegram": {
      "command": "mcp-telegram",
      "args": ["run"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash"
      }
    }
  }
}

Claude Code

claude mcp add telegram -- /path/to/mcp-telegram run

Установите переменные окружения в файле .env или передайте их через --env.

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

19 инструментов, доступных для MCP-клиентов. Сообщения идентифицируются непрозрачными строковыми дескрипторами ("42" для обычных, "s:42" для отложенных) — копируйте их дословно из вывода инструментов для последующих вызовов, никогда не парсите и не создавайте их вручную.

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

Ресурсы закрепленных чатов создаются динамически для каждого закрепленного чата и обновляются в фоновом режиме; клиенты получат resources/list_changed, когда набор изменится.

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

3 параметризованных промпта, которые MCP-клиенты предоставляют как слэш-команды или быстрые действия.

Примеры промптов

Вот несколько примеров промптов, которые можно использовать с ИИ-ассистентами:

Управление сообщениями

• "Проверь, есть ли у меня важные непрочитанные сообщения в Telegram"

• "Сделай краткую выжимку всех моих непрочитанных сообщений в Telegram"

• "Прочитай и проанализируй мои непрочитанные сообщения, подготовь черновики ответов там, где это нужно"

• "Проверь некритичные непрочитанные сообщения и дай мне краткий обзор"

• "Найди сообщения со словом 'счет' в моем рабочем чате за прошлую неделю"

• "Открой контекст вокруг этой ссылки Telegram: https://t.me/example/123"

Организация

• "Проанализируй мои диалоги в Telegram и предложи структуру папок"

• "Помоги мне классифицировать мои чаты в Telegram по важности"

• "Найди все рабочие переписки и предложи, как их организовать"

Коммуникация

• "Следи за конкретным чатом на предмет обновлений по теме [тема]"

• "Напиши вежливый ответ на последнее сообщение в [чат]"

• "Проверь, есть ли в моих чатах неотвеченные вопросы"

• "Разреши эту ссылку на сообщение Telegram и покажи мне контекст ветки"

Резервное копирование и экспорт

• "Сделай резервную копию моей переписки с [контакт] в файл"

• "Экспортируй сообщения за последнюю неделю из [группа]"

• "Сделай резервную копию, включая медиафайлы, чтобы ничего не пропустить"

Суммаризация чатов

Инструмент SummarizeChat поддерживает несколько LLM-провайдеров:

• sampling (экспериментально): использует LLM MCP-клиента через MCP Sampling. Работает только с клиентами, поддерживающими sampling: VS Code, fast-agent, Continue. НЕ работает с Claude Desktop или Claude Code.

• ollama: локальная LLM через Ollama — API-ключ не требуется

• gemini: Google Gemini API

• anthropic: Anthropic Claude API

Настраивается через переменные окружения:

SUMMARIZE_PROVIDER=ollama  # or: sampling, gemini, anthropic
SUMMARIZE_MODEL=           # provider-specific model name

Команды

# Run MCP server (used by MCP clients)
mcp-telegram run

# Login to Telegram
mcp-telegram login --phone +1234567890

# Logout and delete session
mcp-telegram logout

# Securely store config values (macOS Keychain / file on Linux)
mcp-telegram config set TELEGRAM_API_ID 123456789
mcp-telegram config set TELEGRAM_API_HASH abcd1234

# List stored keys
mcp-telegram config list

# Delete a stored value
mcp-telegram config delete TELEGRAM_API_ID

Разрешенные ключи: TELEGRAM_API_ID, TELEGRAM_API_HASH, ANTHROPIC_API_KEY, GEMINI_API_KEY.

Параметры конфигурации

Деструктивные действия

Инструменты вроде DeleteMessage запрашивают подтверждение пользователя через MCP elicitation перед выполнением. Если ваш MCP-клиент не поддерживает elicitation, сервер полагается на инструкции LLM для подтверждения перед выполнением деструктивных операций.

Хранение сессии

• macOS: Безопасно хранится в Keychain.

• Linux/Windows: Хранится в ~/.local/state/mcp-telegram/session.json с правами доступа 0600. Файл в открытом виде — доверяйте учетной записи пользователя, в которой он находится, и отдавайте предпочтение macOS при работе с конфиденциальными аккаунтами.

Значения конфигурации, установленные через mcp-telegram config set (API-ключи, учетные данные Telegram), используют тот же бэкенд: Keychain на macOS, обычный JSON на Linux/Windows.

Лицензия

MIT