mcp-hey

ClaudeにHey.comの受信トレイへの読み取り/書き込みアクセス権を与える、ローカルのModel Context Protocol (MCP) サーバーです。リバースエンジニアリングされたWeb APIを使用します。

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からのメール読み取り

• メールスレッドの送信と返信

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

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

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

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

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

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

セットアップ

前提条件

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

3. 初回実行 — 認証

   bun run dev

   Python認証ヘルパーがHey.comを指すシステムWebViewを開きます。通常通りログインしてください。ヘルパーがセッションクッキーを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）がstdio経由で bun run src/index.ts を起動します。

2. 起動時にサーバーが data/hey-cookies.json を検証します。欠落または期限切れの場合は auth/hey-auth.py を起動し、システムWebViewでHeyを開いて新しいクッキーを書き込みます。

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を参照してください。

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

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

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

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

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

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

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

制限事項

• プロンプトインジェクションのリスク: 多くのMCPサーバーと同様に、このサーバーもthe lethal trifectaの影響を受けます。悪意のあるメールが受信トレイに届いた場合、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が発生する場合は、同時ツール使用数を減らすか、数分待機してください。

• Claude Desktop/CursorでBunがスクリプトを見つけられない — args のパスは相対パスではなく絶対パスである必要があり、クライアントの起動環境から bun が検出可能である必要があります（macOSでは /opt/homebrew/bin/bun のようなフルパスを使用する必要がある場合があります）。

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

コントリビューション

プルリクエストによるコントリビューションを歓迎します。以下をお願いします：

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

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

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

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

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

ライセンス

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