mcp-hey

Локальный сервер протокола контекста модели (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, Drafts, Trash и Spam

• Загрузка вложений и разбор приглашений в календарь из писем

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

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

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

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

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

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

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

Related MCP server: email-mcp

Настройка

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

• 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
   uv pip install -r auth/requirements.txt

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

   bun run dev

   1. Откроется системный webview со страницей входа Hey.com. Войдите в систему как обычно.

   2. Вспомогательный скрипт захватит сессионные cookie в data/hey-cookies.json (права доступа 600) и завершит работу.

   3. Нажмите Ctrl+C — с этого момента ваш MCP-клиент будет запускать свой экземпляр сервера.

   4. Последующие запуски будут использовать сохраненную сессию до истечения ее срока действия.

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

Все клиенты ниже используют одинаковую структуру command/args. На macOS вам почти наверняка потребуется абсолютный путь к bun — см. macOS: bun PATH ниже.

Claude Code

Самый быстрый путь — через CLI:

claude mcp add --transport stdio hey --scope user -- bun run /absolute/path/to/mcp-hey/src/index.ts

Сервер будет доступен сразу в текущей сессии.

Альтернативно, добавьте в .mcp.json в корне вашего проекта (или ~/.claude.json для сервера на уровне пользователя):

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

Если вы редактируете файл напрямую, перезапустите сессию Claude Code, чтобы изменения вступили в силу.

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.

Docker

Dockerfile включен для контейнеризированных развертываний и совместимости с Glama.

Сборка образа:

docker build -t mcp-hey .

Проверка работоспособности сервера (должен вернуть JSON-RPC ответ со списком доступных инструментов):

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | docker run -i mcp-hey

Примечание: Docker-образ запускает только MCP-сервер. Вспомогательный скрипт аутентификации Python и webview-логин внутри контейнера недоступны. Вы должны предоставить существующие сессионные cookie через монтирование тома в data/hey-cookies.json для аутентифицированных операций.

macOS: bun PATH

GUI-приложения (Claude Desktop, Cursor) и оболочки, запущенные через Claude Code, не всегда наследуют PATH из вашего интерактивного терминала, поэтому установленный через Homebrew bun может выдавать ошибку spawn bun ENOENT или просто не подключаться. Исправьте это, используя абсолютный путь к bun в command:

• Apple Silicon Homebrew — /opt/homebrew/bin/bun

• Intel Homebrew — /usr/local/bin/bun

• Ручная установка — выполните which bun в терминале, чтобы найти путь

Пример:

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

Архитектура

Поток данных

1. MCP-клиент (Claude Code, 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
      attachments.ts   # Download attachments, parse calendar invites
    __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 (33 tools)
    hey-features-doc.md  # Hey.com feature mapping

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

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

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

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

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

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

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

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

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

Ограничения

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

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

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

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

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

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

• Только английский интерфейс: сервер парсит HTML-ответы Hey.com и ищет строки на английском языке (например, "You ignored this thread", названия меток, текст кнопок). Он не будет работать корректно, если в Hey.com установлена неанглийская локаль.

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

• Webview аутентификации не открывается — убедитесь, что Python 3.10+ находится в PATH и команда uv 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, уменьшите количество одновременных вызовов инструментов или подождите несколько минут.

• MCP-клиент не может запустить сервер — args должен быть абсолютным путем, а не относительным. Если сам bun выдает ошибку spawn bun ENOENT, см. macOS: bun PATH.

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

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

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

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

• Выполняйте bun run format и bun run lint перед отправкой (на базе Biome).

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

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

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

Лицензия

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