mail-index

mail-index

mail-indexは、受信トレイ全体のプレビューをマシンにダウンロードし、使用中に重要なメッセージの全文を賢く取得します。このローカルインデックスにより、AI エージェントはGmailの検索バーに閉じ込められることなく、メールボックス全体を対象に、本格的な要約と情報の再呼び出しを実行できます。

ローカルMCP サーバーを介して動作するため、あらゆるエージェント（Claude、Codex、任意のMCPクライアント）からクエリできます。ローカル優先で、デフォルトのインデックスがマシンの外に出ることはありません。常時稼働するコネクターが必要な運用者は、代わりに、自身のCloudflareアカウントにオプションのシングルテナント版リモートWorker Deploymentをデプロイできます。mail-indexはホスティングサービスを運営していません。 デフォルトでは読み取り専用で、アーカイブとラベルの編集（gmail.modifyで再認証）や、リモートDeploymentでの下書き（gmail.composeで再認証）を明示的に選択しない限り、メールに変更を加えることはありません。メールの送信や削除は行いません。どちらのオプトインスコープもトークンレベルでは送信が可能なため、この保証はスコープではなく、コード（Gmail runnerの送信ガードとtest/drafts.test.ts）によって実施されます。ADR-0007とADR-0011を参照してください。

_{曖昧な質問をする → ローカルMCP呼び出し1回 → 関連度順で、スニペットを優先した回答。 インタラクティブ版 →}

ステータス：v1.5 — 公開済み。 段階的同期、通信グラフ、関心エンジン、キュレーション、MCP機能一式、書き戻しの各ループは実装とテストが完了し、mail-indexは**npmで公開され、.mcpbバンドルも利用できます。 現在も開発中：バンドル版Option A OAuthクライアントと、署名付きワンクリックインストーラー。アーキテクチャはdocs/PLAN.mdに記載されています。まずはdocs/INSTALL.mdをご覧ください。各リリースはCHANGELOG.md**に記録されています。 [!TIP] v1.5 の新機能 — オプションのリモートデプロイメント。 mail-index は、 お客様自身のアカウントでシングルテナントの Cloudflare Worker としても実行できるようになりました。常時稼働し、cron で同期され、認証済み MCP（および小規模な A2A インターフェース）を介してリモートエージェントからアクセスできます。ローカルサーバーと_同じ_ツールレジストリを提供し、同じ FTS ランキング適合性テストスイートに合格した D1 ストレージドライバーを使用します。また、プッシュにも対応しています。トリガールールが新着メールに一致すると、署名付き Webhook を実行します。時間のかかる O(N) 処理は、コマンドへの引き渡しではなく、キューに登録された Job になります。既存のローカルインデックスから mail-index export → D1 インポートを実行して、新しいデプロイメントにデータを取り込めるため、履歴がすでにインデックス化された状態で開始できます。ローカル CLI と stdio の経路に変更はなく、引き続きデフォルトです。また、mail-index はホスティングサービスを運営しません。Worker はお客様が所有するインフラストラクチャにデプロイするコードです。 docs/INSTALL-worker.md、 docs/WORKER-SEED.md、 ADR-0008 を参照してください。

ローカル環境にも新機能が追加されました。すべての MCP レスポンスに鮮度ブロックが含まれるようになり、古いデータの読み取りがあると、バックグラウンド同期が自動的に開始されます（以前はダイジェストの複合処理のみが対象でした）。

ヒント

v1.4 の新機能 — オプトイン方式のメールボックスへの書き込みと、人が読みやすいラベル。 mail-index では、gog と gws の両方のアダプターで、archive / label CLI コマンドと archive_message / modify_labels MCP ツールを使って、Gmail のメッセージをアーカイブし、ラベルを直接編集できます。デフォルトでは読み取り専用のままです。gmail.modify 権限を付与してオプトインするまで、書き込み機能は利用できません（mail-index が送信や削除を行うことは決してありません。この権限では送信も可能なため、コードガードで制御しています。詳しくは ADR-0011 を参照してください）。アカウントごとに mail-index setup --account <email> --enable-writes または同梱の scripts/enable-writes.sh を使って有効にできます。ラベルはどこでも人が読みやすい名前で表示されます（インデックスが Gmail のラベル一覧をキャッシュし、Label_3546… と 「Expedition Insure」 の相互変換を解決します）。また、label --add/--remove にはわかりやすいラベル名を渡せます。 ADR-0007 を参照してください。

---

仕組み

1. 段階的な同期 — メールボックス全体のメタデータを数分で取得し、本文は選択的に取得します。
2. グラフ — 連絡先、ドメイン、スレッドを対象に、お客様の_人間同士のメール_（一括送信メール以外）から中心性とコミュニティを分析します。
3. 関心度 — 既読、返信、スター、重要度のシグナルから、連絡先ごとのエンゲージメントスコアを算出します。これは_情報を整理するための手がかり_であり、自律的な判断ではありません。
4. 整理 — お客様が（エージェントまたは CLI ウィザードを通じて）重要な人や情報を確認します。そのプロファイルに基づいて、取得する本文が決まります。
5. クエリ — エージェントはローカルで MCP を介して検索し、グラフをたどり、重要なメッセージを読み取ります。

_{重要なメッセージをローカルインデックスに事前登録します。MCP はそこから読み取り、必要な本文がまだ存在しない場合にのみ Gmail にアクセスします。 インタラクティブ版 →}

## クイックスタート

Node 24+ と Gmail の MailSource アダプター（gog（推奨）または gws）が必要です。Gmail を読み取るには Google OAuth クライアントが必要で、 2 つの方法で取得できます。mail-index のベータ版クライアントを使う （Google Cloud の設定は不要です。 アクセスをリクエスト して、約 100 人のテストリストに参加してください）か、Google Cloud クライアントを 自分で用意する（上限なし、リクエスト不要。設定方法をご案内します）方法です。 docs/INSTALL.md §2 および docs/oauth-and-verification.md をご覧ください。

npm install -g mail-index                    # or: pnpm add -g mail-index

mail-index init                              # scaffold the config
# …connect a mailbox (own OAuth client, read-only) — see docs/INSTALL.md §2 / agent-install.md…
mail-index sync  --account personal --since 6mo
mail-index graph build --account personal
mail-index search "that contract we discussed"

（ソースからのインストールを希望する場合：git clone …、pnpm install && pnpm build を実行し、続いて node dist/cli/index.js … としてバイナリを実行します。）

Claude に追加する

MCP サーバーは 1 ステップで登録できますが、先にメールボックスを接続する必要があります （手順についてはガイドをご覧ください）。.mcpb／claude mcp add で追加されるのは サーバーだけです。アダプターのインストール、サインイン、同期は行われません。

• Claude Code： claude mcp add --transport stdio mail-index -- npx -y -p mail-index mail-index-mcp （Windows では、先頭に cmd /c を付けます：… -- cmd /c npx -y -p mail-index mail-index-mcp — npx／.cmd を直接指定しても起動しません。docs/INSTALL.md §7 をご覧ください。）
• 任意の MCP クライアント（手動）：

  { "mcpServers": { "mail-index": { "command": "mail-index-mcp" } } }
  

• Claude Desktop： .mcpb バンドル をダウンロードしてダブルクリックします（ベータ期間中は未署名のため、システム設定／Windows SmartScreen で許可が必要な場合があります）。バンドルは自己完結型で （依存関係が同梱され、Claude Desktop にバンドルされた Node で実行されるため、npx、 ネットワーク、システムの Node は不要です）、Windows／macOS／Linux のいずれでも同じように インストールできます。アダプターのインストール、サインイン、同期も行う署名済みの オールインワンインストーラーは、まだ開発中です。claude:// のインストールリンクはありません。

よくある操作をエージェントに教えましょう。 MCP サーバーは、エージェントが mail-index を使うべき場面（購入、領収書、予約、「誰が何と言ったか」、「最近の状況を教えて」など）を すでに伝えています。また、リポジトリには、よく使われる手順（購入情報の検索、最近の状況の確認、 連絡先からのメールの検索、送信者の要約）をまとめた Claude 用 Agent Skill が含まれています。Claude Code／Desktop に追加するには：

mkdir -p ~/.claude/skills && cp -R skills/mail-index ~/.claude/skills/

認証、キュレーション、エンリッチメント、定期同期、デスクトップアプリ特有の注意点についての 詳しい手順 → docs/INSTALL.md。エージェントを使ってセットアップする場合 → docs/agent-install.md。

想定される所要時間とストレージ

インデックスには、すべてのメッセージのメタデータと、必要な場合に限り全文が保存されます。 そのため、メールボックスのサイズではなくメッセージの 件数 に応じて増加し、 Gmail 全体の約 1.5% です。初回同期は毎分約 50 件（初回のみ。以降は差分同期）で、 検索は即座に行えます。まずは --since 1mo を指定すれば、数分で活用できます。 その後、対象期間を広げてください。容量の目安と拡張方法 → docs/INSTALL.md §9。

Gmail 検索より軽量な理由

標準的な Gmail API MCP は、クエリベースの検索ツールです。正確なクエリが必要で、 呼び出しごとにネットワーク通信が発生し、未加工のデータがモデルのコンテキストに そのまま渡されます。一方、mail-index はローカルの想起インデックスから 曖昧な 質問にも答えます。実際のメールボックスで 100 問のテストを実施したところ、 すべての質問に答えるのに必要なトークン数は 15 分の 1 でした。しかも、クエリベースの MCP にはそもそも対応する機能がない、要約、人間関係、約束に関する質問では、差がさらに広がります。

カテゴリ別の表、メッセージを 1 件読む場合の比較、ツールごとの全体像、および再現方法 → docs/COMPARISON.md。

Stack

TypeScript · node:sqlite（ネイティブ依存関係なし）· SQLite FTS5 · Graphology · @modelcontextprotocol/sdk。Node 24 以降。差し替え可能な MailSource アダプターを使用し、Gmail トランスポートとして gog（推奨）と Google の gws の 2 種類が付属します。

CLI

2 つの実行ファイルが付属します。mail-index（CLI）と mail-index-mcp（stdio MCP サーバー）です。

mail-index init                          Scaffold the operator config + data dir
mail-index sync    --account <a> [--since 30d|1mo] [--all] [--query <q>] [--limit N]
mail-index sync    --all-accounts        Sync every account by its policy presets
mail-index enrich  --account <a> [--profile | --rule direct|all] [--sender <s>] [--match <fts>] [--limit N]
mail-index graph   build [--account <a> | --all-accounts]
mail-index curate  [--account <a>]       Interactive curation wizard (no-agent fallback)
mail-index compact [--account <a>] [--now]   Demote summarized bulk bodies (ADR-0003)
mail-index search  <terms> [--account <a>] [--limit N] [--enrich]
mail-index show    <account:message-id>  Print a message (auto-enriches a meta row)
mail-index open    <account:message-id>  Print the provider web URL (no fetch)
mail-index archive <account:message-id>  Archive (drop INBOX) — opt-in write; needs gmail.modify
mail-index label   <account:message-id> [--add <l>]... [--remove <l>]...  Opt-in write; needs gmail.modify
mail-index status  [--json]              Per-account freshness + counts

書き込みはデフォルトで無効です。アカウントのアーカイブとラベル編集を有効にするには、 mail-index setup --account <email> --enable-writes（または付属の scripts/enable-writes.sh <email>）を実行し、gmail.modify の許可を付与します。リモートの Deployment では、create_draft が 3 つ目のオプトイン書き込み機能です。別途 gmail.compose の許可（&drafts=1）を付与すると有効になります。どちらのスコープもトークンレベルでは送信が可能ですが、mail-index が送信や削除を行うことはありません。Gmail ランナーは送信経路を拒否し、 test/drafts.test.ts は新たな送信経路が追加されると CI を失敗させます。 ADR-0007 と ADR-0011 を参照してください。

ドキュメント

• docs/INSTALL.md — 一般的な導入手順（インストール、 MailSource の認証、初期化、同期、キュレーション、エンリッチ、MCP サーバーの追加、 定期同期のスニペット）。
• docs/MCP.md — エージェントのインテグレーター向け、18 個のツールの MCP リファレンス： 引数、簡潔な結果形式、index_as_of の鮮度およびコマンド引き継ぎの契約。
• docs/ADAPTERS.md — MailSource の契約と、新しいアダプター（gws、gog、gmail-rest）の 作成方法および契約テストの実施方法。
• docs/INSTALL-worker.md — 任意のシングルテナント型リモート Worker を独自の Cloudflare アカウントにデプロイする手順： D1／Queue／KV リソース、シークレット、オペレーターの許可リスト、エージェントの接続、検証チェックリスト。
• docs/STAFF-SENT-EVIDENCE.md — 無効化された非公開の最新 SENT エビデンスサービス、呼び出し元／許可の境界、アクティベーションの前提条件。
• docs/WORKER-SEED.md — Gmail からメールボックス全体を再同期する代わりに、既存のローカルインデックス（mail-index export → import）から新しい Deployment の D1 にデータを投入する手順。
• docs/PLAN-worker.md — リモート Deployment の設計： 固定された決定事項、マイルストーン、ローカルとリモートの同等性に関する制約。
• CHANGELOG.md — リリース済みの各バージョンでの変更点。
• docs/PLAN.md — アーキテクチャ、データモデル、主要な決定事項（ADR の要約）。
• SECURITY.md + docs/THREAT-MODEL.md — プライバシーに関する方針、信頼境界、プロンプトインジェクションへの対応方針、および 「主張を自分で検証する」ための手順書。ローカルのみという約束は、CI の egress guard test によって強制されます。コア（src/）は ネットワーク呼び出しを行いません。唯一の例外は、オプトアウト可能な起動シムのセルフアップデーター （bin/selfupdate.mjs、npm バージョンの確認は頻度制限付き、無効化するには MAIL_INDEX_NO_AUTOUPDATE=1）で、同じガードによる監査を受けています。

About

Unsold Group が開発しています。旅行・インシュアテック企業として、AI ネイティブな事業運営の基盤となる、ローカルファーストでエージェントネイティブなインフラを構築しています。AI が活用できる、実際にクエリ可能なコンテキストを提供します。 mail-index はその取り組みの一環です。エージェントにメールボックスの鍵を渡さずに、メールボックスの永続的な記憶を提供します。

詳細：unsold.group/al

プロジェクトの成長

フィードバックとお問い合わせ

ローカルインストールでは、テレメトリは一切ありません。セルフホストのリモートデプロイメントでは、運用者が POSTHOG_PROJECT_TOKEN（INSTALL-worker.md）を設定した場合に限り、 ツールの使用状況に関するメタデータ（引数や結果は含みません）が送信されます。皆さんからお知らせいただいた内容しか分からないため、フィードバックを心から歓迎します。

• 💬 ディスカッション — 質問、アイデア、使い方
• 🐞 バグを報告 · 💡 機能をリクエスト
• 🔒 セキュリティ／プライバシーに関する問題 → SECURITY.md（非公開）
• 🌐 unsold.group/al

エージェントに 「mail-index のバグを報告して」 と伝えるだけでもかまいません。MCP サーバーが、報告を送信するための GitHub リンクをエージェントに提示します（サーバーが自ら送信することはありません）。詳しくは SUPPORT.md をご覧ください。

ライセンス

MIT