mbox-mcp

mbox-mcp

ローカルのメールアーカイブ用のMCPサーバーです。Google Takeout の .mbox エクスポート、または .eml ファイルのフォルダーを指定すると、Claude に次のような質問ができます。

• 「このアーカイブで、最も多くメールを送った相手は誰ですか？」
• 「大家が賃貸契約の更新に触れていたメッセージを探して」
• 「2026 年初頭の [email protected] とのやり取りを要約して」

すべてのデータはお使いのマシンから外に出ません。 OAuth もアプリパスワードも IMAP 接続もクラウドも不要です。他のメール MCP サーバーはすべて稼働中のアカウントに接続しますが、このサーバーはすでにお持ちのアーカイブファイルを読み込みます。Takeout エクスポートに Gmail の 15 年分のメールが保存されている場合に、まさに最適です。

クイックスタート

Claude Code

claude mcp add mbox -- npx -y mbox-mcp

Claude Desktop — claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "mbox": {
      "command": "npx",
      "args": ["-y", "mbox-mcp"]
    }
  }
}

その後、次のように指示します。「C:\Takeout\Mail\All mail Including Spam and Trash.mbox を開いて、内容を教えてください。」

ツール

ツール	機能
open_archive	.mbox ファイルまたは .eml ディレクトリをインデックス化します。メッセージ数、日付範囲、送信者の上位を表示します
search_messages	キーワード、送信者、件名、日付範囲で検索します。範囲を指定した本文検索にも対応します
get_message	1 件のメッセージを完全に解析します。デコード済みの本文、ヘッダー、添付ファイル名とサイズを取得します

大規模なアーカイブ向けに設計

Takeout の mbox は複数ギガバイトになり、メッセージ数が 10 万件を超えることもよくあります。この設計では、必要最小限のデータを遅延読み込みします。

• ストリーミングインデックス — 8 MiB のチャンクで 1 回読み込み、バイトオフセットを記録します。エンベロープ解析（送信者、件名、日付、RFC 2047 デコード）では、現在のメッセージの先頭 16 KiB だけを保持します。
• 必要に応じた完全な MIME 解析 — メッセージを読み込む際は、そのメッセージだけを解析します（postal-mime を使用：ネストされたマルチパート、文字セット、quoted-printable/base64）。添付ファイルは名前とサイズのみを一覧表示し、コンテキストに内容を出力することはありません。
• 正確な本文検索 — body_query は、エンベロープのフィルターにすでに一致したメッセージだけを完全に解析します。スキャン上限で処理を停止し、スキャンした件数を報告するため、モデルは最初に送信者または日付で絞り込むべきか判断できます。
• 更新を考慮したキャッシュ — アーカイブはプロセスごとに 1 回インデックス化され、ファイルが変更されると再インデックス化されます。

注意事項と制限

• mbox の種類：Takeout と Thunderbird は mboxrd を生成します（本文中の From 行は >From として引用されます）。そのため、正しく分割できます。本文中の From 行が引用されないプレーンな mboxo アーカイブでは、過剰に分割されることがあります。
• 添付ファイルの内容が返されたり、どこかに書き込まれたりすることはありません。
• PST/OST と Maildir は、現時点では対象外です。

開発

npm install
npm test                 # offline tests — synthetic archives built in-suite
npm run build            # tsc → dist/
node scripts/smoke.mjs   # end-to-end: generates an archive, drives the server over stdio

アーキテクチャ：src/archive.ts（ストリーミングインデクサー、ヘッダーのデコード、エンベロープのフィルタリング）と src/reader.ts（メッセージごとの MIME 解析）は純粋なロジックです。src/index.ts は MCP の接続部分です。テストスイートにはチャンク境界のプロパティテストが含まれており、特殊な 17 バイトのチャンクでインデックス化しても、ファイル全体を読み込んだ場合と同一のインデックスが生成されることを確認します。

ライセンス

MIT