mcp-hey

Локальный сервер протокола Model Context Protocol (MCP), который предоставляет Claude доступ на чтение/запись к вашему почтовому ящику Hey.com через реверс-инжиниринг веб-API.

mcp-hey состоит из двух частей: MCP-сервера на Bun/TypeScript, который предоставляет инструменты Hey через stdio, и небольшого вспомогательного скрипта на Python, использующего системный webview для захвата сессионных cookie при входе в систему. Все работает локально — никакого облачного ретранслятора, никаких сохраненных учетных данных, только сессионные cookie на диске.

Внимание — неофициальный API. Hey.com не публикует публичный API; mcp-hey использует реверс-инжиниринг веб-эндпоинтов и связывает их с HTTP-запросами, идентичными браузерным. Все может сломаться без предупреждения. Текущая задокументированная поверхность находится в docs/API.md.

Возможности

• Чтение писем из Imbox, Feed, Paper Trail, Set Aside и Reply Later

• Отправка и ответы на цепочки писем

• Поиск писем по всем папкам

• Организация почты (отложить, ответить позже, пропустить/заблокировать, поднять вверх)

• Локальный кэш SQLite для быстрого повторного чтения и полнотекстового поиска

• Легковесность — около 30 МБ оперативной памяти в режиме ожидания

• Идентичные браузерным заголовки и TLS-профиль для предотвращения обнаружения

• Работает полностью на вашем компьютере; транспорт stdio без выхода в сеть

Настройка

Предварительные требования

• Bun 1.1 или новее

• Python 3.10 или новее (плюс UV, если вы хотите следовать инструментарию Python в CLAUDE.md)

• Учетная запись Hey.com

• Платформа: разработано и протестировано на macOS и Linux. Пользователям Windows, скорее всего, потребуется WSL — бэкенд pywebview для Windows в настоящее время не используется.

Установка

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

   git clone https://github.com/Sealjay/mcp-hey.git
   cd mcp-hey

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

   bun install
   pip install -r auth/requirements.txt

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

   bun run dev

   Вспомогательный скрипт аутентификации на Python открывает системный webview, направленный на Hey.com. Войдите в систему как обычно; скрипт захватит сессионные cookie в data/hey-cookies.json (права доступа установлены на 600) и завершит работу. Последующие запуски будут использовать сохраненную сессию до истечения срока ее действия.

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

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "hey": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-hey/src/index.ts"]
    }
  }
}

Перезапустите Claude Desktop. Вы должны увидеть hey в списке доступных интеграций.

Cursor

Добавьте в ~/.cursor/mcp.json:

{
  "mcpServers": {
    "hey": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-hey/src/index.ts"]
    }
  }
}

Перезапустите Cursor.

Архитектура

Поток данных

1. MCP-клиент (Claude Desktop / Cursor) запускает bun run src/index.ts через stdio.

2. При запуске сервер проверяет data/hey-cookies.json. Если файл отсутствует или истек срок действия, он запускает auth/hey-auth.py, который открывает Hey в системном webview и записывает свежие cookie.

3. Вызовы инструментов обращаются к Hey.com напрямую с реалистичными заголовками браузера; ответы парсятся (HTML через node-html-parser) и кэшируются в SQLite.

4. Операции записи получают свежий CSRF-токен перед отправкой.

Структура проекта

mcp-hey/
  src/
    index.ts           # MCP server entry point
    hey-client.ts      # HTTP client with cookie injection
    session.ts         # Session management and validation
    errors.ts          # Error classes and sanitisation
    cache/             # SQLite cache (db, schema, messages, search)
    tools/             # MCP tool implementations
      read.ts          # Reading and listing
      send.ts          # Send, reply, forward
      organise.ts      # Triage, labels, bubble up, etc.
      http-helpers.ts  # Shared CSRF retry and endpoint fallback
    __tests__/         # Test suites
  auth/
    hey-auth.py        # Python auth helper (pywebview)
    requirements.txt
  data/
    hey-cookies.json   # Session storage (gitignored, chmod 600)
  docs/
    API.md             # Hey.com API surface documentation
    TOOLS.md           # MCP tool reference (41 tools)

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

41 инструмент, сгруппированный по функциям. См. docs/TOOLS.md для параметров, форматов возвращаемых данных и поведения при ошибках.

Конфиденциальность и безопасность

• Учетные данные никогда не сохраняются — только сессионные cookie, записанные с правами доступа 600.

• Аутентификация происходит полностью внутри собственной страницы входа Hey (системный webview).

• Все данные остаются на вашем компьютере. Этот проект не отправляет никакой телеметрии.

• MCP использует транспорт stdio — сервер никогда не открывает сетевой порт для прослушивания.

• Валидность сессии проверяется при запуске и перед выполнением чувствительных операций.

См. SECURITY.md для получения информации о том, как сообщать об уязвимостях.

Ограничения

• Риск инъекции промптов: как и многие MCP-серверы, этот подвержен смертельному трио. Вредоносное письмо, попавшее в ваш ящик, может попытаться дать указание Claude переслать другие сообщения. Относитесь к поверхности инструментов соответствующим образом и проверяйте рискованные действия перед их одобрением.

• Неофициальный API: фронтенд Hey.com может измениться без предупреждения и сломать работу. Ожидайте периодических поломок и проверяйте docs/API.md на наличие известных изменений.

• Нет уведомлений в реальном времени: только опрос.

• Загрузка вложений пока не поддерживается.

• Одна учетная запись на экземпляр MCP-сервера.

• Риск для учетной записи: агрессивные или ненормальные паттерны доступа теоретически могут активировать системы защиты от злоупотреблений Hey. Сервер соблюдает заголовки x-ratelimit и использует экспоненциальную задержку, но гарантий нет.

Устранение неполадок

• Webview аутентификации не открывается — убедитесь, что Python 3.10+ находится в PATH и команда pip install -r auth/requirements.txt выполнена успешно. В Linux убедитесь, что доступен бэкенд webview (команда python -c "import webview" не должна выдавать ошибок).

• Ответы 401/403 после недель использования — ваша сессия Hey истекла. Удалите data/hey-cookies.json и снова запустите bun run dev для повторной аутентификации.

• Ограничения скорости (429) — клиент соблюдает заголовки x-ratelimit и делает паузы. Если вы видите постоянные ошибки 429, уменьшите количество одновременных вызовов инструментов или подождите несколько минут.

• Bun не может найти скрипт в Claude Desktop/Cursor — путь в args должен быть абсолютным, а не относительным, и bun должен быть доступен из среды запуска клиента (на macOS это может означать использование полного пути, например /opt/homebrew/bin/bun).

• Имя cookie изменилось — Hey уже переименовывал сессионные cookie (например, _hey_session → session_token, см. CLAUDE.md для журнала). Если аутентификация молча завершается с ошибкой после обновления Hey, захватите свежие cookie и сравните их.

Вклад в проект

Вклад приветствуется через pull request. Пожалуйста:

• Используйте conventional commits (feat, fix, docs, refactor, test, perf, cicd, revert, WIP).

• Запустите bun run format и bun run lint перед отправкой.

• Убедитесь, что bun test проходит успешно.

• Обновите docs/API.md, если вы обнаружите или измените поведение API Hey.com.

См. CLAUDE.md для полного рабочего процесса разработки.

Лицензия

Лицензия MIT — см. LICENCE.