mcp-hey

Hey.comの受信トレイに対して、リバースエンジニアリングされたWeb API経由でClaudeが読み取り/書き込みアクセスできるようにするローカルModel Context Protocol (MCP) サーバーです。

mcp-heyは2つのパーツで構成されています。Heyのツールをstdio経由で公開するBun/TypeScript製のMCPサーバーと、ログイン時にシステムWebviewを使用してセッションクッキーを取得する小さなPythonヘルパーです。すべてローカルで実行され、クラウド中継や認証情報の保存は行わず、セッションクッキーのみがディスクに保存されます。

警告 — 非公式APIです。 Hey.comは公開APIを提供していません。mcp-heyはWebエンドポイントをリバースエンジニアリングし、ブラウザと同一のHTTPリクエストを送信します。予告なく動作しなくなる可能性があります。現在ドキュメント化されているインターフェースは docs/API.md にあります。

機能

• Imbox、Feed、Paper Trail、Set Aside、Reply Later、Drafts、Trash、Spamからのメール読み取り

• 添付ファイルのダウンロードおよびメールからのカレンダー招待の解析

• メールスレッドの送信および返信

• ボックスを横断したメール検索

• メールの整理（Set aside、Reply later、Screen in/out、Bubble up）

• 高速な繰り返し読み取りと全文検索のためのローカルSQLiteキャッシュ

• 軽量 — アイドル時のメモリ使用量は約30MB

• 検知を回避するためのブラウザと同一のヘッダーおよびTLS設定

• すべてマシン上で実行 — ネットワーク公開なしのstdioトランスポート

Related MCP server: email-mcp

セットアップ

前提条件

• Bun 1.1以降

• Python 3.10以降（CLAUDE.mdのPythonツールを使用する場合はUVも必要）

• 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. ヘルパーがセッションクッキーを 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

コンテナ化されたデプロイメントおよびGlama互換性のためにDockerfileが含まれています。

イメージのビルド:

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ログインはコンテナ内では利用できません。認証された操作を行うには、既存のセッションクッキーを data/hey-cookies.json にボリュームマウントする必要があります。

macOS: bun PATH

GUIアプリ（Claude Desktop、Cursor）やClaude Codeによって起動されたシェルは、インタラクティブターミナルのPATHを継承しない場合があるため、Homebrewでインストールされた bun が spawn bun ENOENT エラーになったり、接続できなかったりすることがあります。command に bun への絶対パスを指定することで解決します：

• 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 を起動し、システムWebviewでHeyを開いて新しいクッキーを書き込みます。

3. ツール呼び出しはブラウザと同一のヘッダーを使用してHey.comに直接送信されます。レスポンスは解析（node-html-parserによるHTML解析）され、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 を参照してください。

プライバシーとセキュリティ

• 認証情報は一切保存されません。保存されるのはセッションクッキーのみで、600 パーミッションで書き込まれます。

• 認証はすべてHey自身のログインページ（システムWebview）内で行われます。

• すべてのデータはマシン内に留まります。このプロジェクトによってテレメトリが送信されることはありません。

• MCPはstdioトランスポートを使用するため、サーバーがネットワークリスナーを開くことはありません。

• セッションの有効性は起動時および機密操作の前にチェックされます。

脆弱性の報告方法については SECURITY.md を参照してください。

制限事項

• プロンプトインジェクションのリスク: 多くのMCPサーバーと同様に、このサーバーも the lethal trifecta の影響を受けます。受信トレイに届いた悪意のあるメールが、他のメッセージを流出させるようClaudeに指示する可能性があります。ツールを使用する際はそのリスクを考慮し、危険な操作は承認前に確認してください。

• 非公式API: Hey.comのフロントエンドは予告なく変更され、動作しなくなる可能性があります。時折発生する不具合を想定し、既知の変更点については docs/API.md を確認してください。

• リアルタイム通知なし: ポーリングのみです。

• 添付ファイルのアップロードはまだサポートされていません。

• MCPサーバーインスタンスごとに1つのアカウントのみ対応しています。

• アカウントのリスク: 過度または異常なアクセスパターンは、理論上Heyの不正利用防止システムをトリガーする可能性があります。サーバーは x-ratelimit ヘッダーを尊重し、指数バックオフを行いますが、保証はありません。

• 英語UIのみ: サーバーはHey.comのHTMLレスポンスを解析し、英語の文字列（例: "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 を参照してください。

• クッキー名が変更された — Heyは過去にセッションクッキーの名前を変更したことがあります（例: _hey_session → session_token、docs/API.md の変更履歴を参照）。Heyのアップデート後に認証がサイレントに失敗する場合は、新しいクッキーを取得して比較してください。

コントリビューション

プルリクエストによるコントリビューションを歓迎します。以下の点にご協力ください：

• Conventional Commits (feat, fix, docs, refactor, test, perf, cicd, revert, WIP) を使用してください。

• プッシュ前に bun run format と bun run lint を実行してください（Biome を使用）。

• bun test がパスすることを確認してください。

• Hey.com APIの動作を発見または変更した場合は docs/API.md を更新してください。

完全な開発ワークフローについては CLAUDE.md を参照してください。

ライセンス

MITライセンス — LICENCE を参照してください。