Mcp Hey

mcp-hey

Claude に Hey.com の受信トレイへの読み書きアクセスを提供する、ローカル MCP サーバーです。Bun／TypeScript サーバーが stdio 経由でツールを公開し、小さな Python ヘルパーがログイン時にシステムの WebView を通じてセッション Cookie を取得します。クラウドリレーも、認証情報の保存もありません。

非公式 API です。 Hey.com に公開 API はありません。mcp-hey はブラウザーと同一のリクエストで Web エンドポイントを利用するため、予告なく動作しなくなる可能性があります。現在の API 範囲は docs/API.md をご覧ください。

セットアップ

前提条件： Bun 1.1 以降、Python 3.10 以降、Hey.com アカウント。macOS と Linux でテスト済みです。Windows では WSL が必要になる可能性があります。

git clone https://github.com/Sealjay/mcp-hey.git
cd mcp-hey
bun install
uv pip install -r auth/requirements.txt
bun run dev   # first run: log in to Hey in the webview, then Ctrl+C

ヘルパーはセッション Cookie を data/hey-cookies.json（モード 600）に保存します。以降の実行では、期限切れになるまで同じ Cookie が再利用されます。

MCP クライアントの設定

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

クライアント	場所
Claude Code	claude mcp add --transport stdio hey --scope user -- bun run /absolute/path/to/mcp-hey/src/index.ts、または上記のブロックを .mcp.json に追加
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Cursor	~/.cursor/mcp.json

絶対パスを使用してください。GUI アプリからはシェルの PATH を参照できないことがよくあります。そのため、spawn bun ENOENT が表示された場合は、command に which bun の出力を設定してください（Homebrew の場合：/opt/homebrew/bin/bun）。

Docker： docker build -t mcp-hey . を実行し、続けて printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | docker run -i mcp-hey を実行します。イメージにはログインヘルパーが含まれていないため、既存の Cookie を data/hey-cookies.json にマウントしてください。

ツール

ツールは 37 種類です。パラメーター、戻り値の形式、エラーについては docs/TOOLS.md をご覧ください。

カテゴリー	ツール
読み取り	hey_list_emails (imbox, feed, paper_trail, trash, spam, drafts, sent), hey_imbox_summary, hey_list_set_aside, hey_list_reply_later, hey_list_screener, hey_read_email, hey_download_attachment, hey_get_calendar_invite
ラベルとコレクション	hey_list_labels, hey_list_label_emails, hey_label, hey_list_collections, hey_list_collection_emails, hey_collection
送信と下書き	hey_send_email, hey_reply, hey_forward, hey_save_draft, hey_edit_draft, hey_delete_draft
トリアージ	hey_set_aside, hey_unset_aside, hey_reply_later, hey_remove_reply_later, hey_move_to, hey_set_status, hey_mark_unseen, hey_mark_seen, hey_read_status, hey_thread_mute
目立たせる	hey_bubble_up, hey_bubble_up_if_no_reply, hey_pop_bubble
スクリーナー	hey_screen, hey_screen_by_id
検索とキャッシュ	hey_search, hey_cache_status

送信者グループ

ツールが返すすべてのメッセージには sender_group が含まれます。これは、その送信者からの新着メールをHeyがどこに届けるか（imbox、feed、paper_trail、screened_out、それ以外は unknown）を示すもので、連絡先ページの「メールの配信先…」設定に基づきます。メッセージではなく、送信者についての情報です。

hey_search、hey_list_set_aside、hey_list_reply_later、hey_list_label_emails、hey_list_collection_emails では、任意の group を指定できます。たとえば group: ["imbox"] を指定すると、ニュースレターや領収書を除外できます。デフォルト（HEY_SENDER_GROUPS=filter）では、ツールはローカルキャッシュからタグを付け、フィルターを指定した呼び出しの場合にのみHeyに問い合わせます。on では呼び出しのたびに一部の送信者を検索し、off ではフィールドを除外します。詳しくは、送信者グループによるフィルタリングをご覧ください。

アーキテクチャ

コンポーネント	説明
MCP サーバー	MCP TypeScript SDK v2 を使用した Bun／TypeScript 実装です。stdio は MCP 2026-07-28 とそれ以前のリビジョンに対応し、アイドル時のメモリ使用量は約 30 MB です
認証ヘルパー	Python／pywebview を使用し、Cookie がないか期限切れの場合にのみ起動します
キャッシュ	メッセージ、スレッド、全文検索用のローカル SQLite です

リクエストにはブラウザーを模したヘッダーが付き、書き込み操作の前には最新のCSRFトークンを取得します。また、クライアントは x-ratelimit に応じてリクエスト間隔を空けます。

プライバシーと制限事項

• セッションCookieのみを保存します（モード 600）。ログインはHeyのページ上で行います。テレメトリーはなく、ネットワークリスナーもありません。
• プロンプトインジェクション： このサーバーには致命的なトライフェクタがあります。悪意のあるメールによって、Claudeがほかのメールを外部に流出させようとする可能性があるため、リスクのある操作は承認前に確認してください。
• カレンダーイベントの作成、添付ファイルのアップロード、リアルタイム通知には対応していません。インスタンスごとに1つのアカウントを使用します。
• HeyのHTMLは英語のUI文字列を基準に解析されるため、Heyの表示言語が英語以外の場合は動作しません。
• レート制限への対応を行っていても、通常とは異なるアクセスパターンによりHeyの不正利用対策が作動する可能性があります。

脆弱性は SECURITY.md から報告してください。

トラブルシューティング

• Webviewが開かない場合： Python 3.10+ がインストールされていることと、python -c "import webview" が動作することを確認してください（LinuxではWebviewバックエンドが必要です）。
• 数週間後に 401／403 が発生する場合： セッションの有効期限が切れています。data/hey-cookies.json を削除して、bun run dev を実行してください。
• 429 が継続して発生する場合： ツールの同時使用を減らすか、数分待ってください。
• Heyのアップデート後に認証が通知なく失敗する場合： Heyでは以前、セッションCookieの名前が変更されています。docs/API.md の変更履歴をご覧ください。

貢献

Conventional Commitsを使用してください。bun run format、bun run lint、bun test がすべて成功する必要があります。Heyの動作が変わった場合は docs/API.md を更新してください。詳細は CLAUDE.md をご覧ください。

ライセンス

MIT。LICENCEをご覧ください。