mailbox-mcp

mailbox-mcp は、メールを Claude Code、Cursor、Windsurf、または Model Context Protocol に対応するあらゆる AI ツールに接続する MCP サーバーです。ターミナルと Gmail を行き来する代わりに、AI にあの請求書を探すよう頼んだり、スレッドを要約するよう頼んだり、返信の下書きを作るよう頼んだりすれば、実行してくれます。

ほかの 60 以上のメール用 MCP サーバーとの違い：

• 複数アカウントを 1 つのサーバーで。 仕事用メール、個人用メール、顧客アカウントなど、すべて 1 つのサーバーから利用できます。別々のインスタンスを起動する必要はありません。
• Gmail だけではありません。 Gmail（完全な API）、あらゆる IMAP/SMTP プロバイダー（ProtonMail、企業メール、セルフホスト環境）、JMAP（Fastmail、Stalwart、Topicbox）に対応しています。ツールのコードを一行も変更せずにプロバイダーを追加できます。
• 信頼できない入力に備えた設計。 隠しテキストの除去、ランダムな nonce によるフェンス、メールがアカウントから送信される前の確認、アカウントごとの読み取り専用モードと下書き専用モード、認証情報の暗号化（AES-256-GCM）、TLS の強制、SSRF 対策を備えています。詳しくはセキュリティをご覧ください。
• 重要なワークフロー向けのツール。 検索、閲覧、送信、返信、転送、下書き、ラベル、フィルター、テンプレート、署名、自動返信、添付ファイル、配信停止などに対応しています。
• ネイティブ依存関係はゼロ。 純粋な Node.js で実装されています。どこでもインストールして実行できます。

セキュリティ

モデルにメールボックスへのアクセスを許可することは、見知らぬ人が書いたテキストへのアクセスも許可するということです。送信者は、モデルが読むメールの件名、本文、ヘッダー、添付ファイル名をすべて制御できます。そのため、リスクは 2 つあります。メールに仕込まれた指示にモデルが従うことと、送信すべきでない宛先にモデルがメールを送ることです（この種の指示でよくある目的は、スレッドを転送させたり、別のメッセージの内容を返信させたり、秘密情報を外部アドレスに送らせたりすることです）。mailbox-mcp は、この 2 つのリスクの間に複数の防護層を設けています。

信頼できないコンテンツをフェンスで囲みます。 メールに由来するすべての内容を [UNTRUSTED_<KIND>_<nonce>] ... [/UNTRUSTED_<KIND>_<nonce>] マーカーで囲み、サーバーの MCP 指示によって、クライアントにマーカー内のテキストは報告すべきデータであり、従うべき指示ではないと伝えます。nonce はツールの応答ごとに新しく選ばれるランダムな 16 進文字列なので、メールの内容がフェンスを早期に閉じたり、偽のフェンスを開いたりすることはできません。また、大文字・小文字の違いや Unicode の類似文字を含め、マーカーに見える内容はすべて、モデルに届く前に角括弧を置き換えます。

隠しテキストは除去され、そのことが通知されます。 HTML のみのメッセージは、メールクライアントで実際に表示される内容に変換されます。display:none、visibility:hidden、opacity:0、ゼロまたは極小のフォントサイズ、背景と同じ色のテキスト（白地に白文字）、hidden 属性、aria-hidden、画面外への配置、max-height:0; overflow:hidden を使ったプレヘッダーの手法で隠された要素は、コメント、スクリプト、スタイル、テンプレートとともに削除されます。ゼロ幅文字や双方向制御文字は、すべての本文、件名、ヘッダー、ファイル名から除去されます。何かが削除された場合は、削除した文字数を示す警告が応答の末尾に表示されます。そのため、ユーザーに見える内容とモデルに見える内容が異なるメッセージは、気づかれないまま修正されるのではなく、警告されます。 メール送信前の確認。 アカウントがこれまでに送信も受信もしたことのないアドレス宛てに送信するには、confirm_new_recipient: true が必要です。エラーには新しいアドレスが表示されます。アカウント自身のドメイン以外に転送するには、confirm_external_forward: true が必要です。クライアントには、ユーザー自身がその宛先を指定した場合に限ってこれらのフラグを渡し、メールの指示を受けて渡さないよう伝えます。どちらのチェックもデフォルトで有効です。

アカウントごとのモード。 アカウントには、宛先の許可リスト（完全一致のアドレスと @domain パターンを指定でき、それ以外は拒否されます）、draftsOnly フラグ（送信ツールの代わりに、確認用の下書きを作成します）、readOnly フラグ（すべての書き込みツールが拒否されますが、検索と読み取りは引き続き利用できます）を設定できます。これらは accounts.json で設定するか、アカウント作成時に指定します。どのツールからも制限を緩められないため、セッションを乗っ取られても無効化されません。アカウントの安全設定を参照してください。

ツールのアノテーション。 49 個すべてのツールに MCP の readOnlyHint、destructiveHint、idempotentHint、openWorldHint アノテーションが付いているため、クライアントは読み取りを自動承認し、送信、削除、設定変更を行う操作の前には必ず確認を求められます。

上限とログ。 1 分あたりの送信は最大 10 件、デフォルトではアカウントごとにローリング 24 時間あたり 100 件です。1 日の送信数はディスクに保存され、再起動後も保持されます。サーバー経由の送信はすべて、宛先とともに ~/.mailbox-mcp/sends.jsonl に記録され、一括ラベル付けや一括ゴミ箱移動の操作はすべて、取り消し ID とともに transactions.jsonl に記録されます。

以下の 3 つのオプションは、モデルに適切な振る舞いを求めるのではなく、モデルの外部で制限を適用します。いずれもデフォルトでは無効です。

帯域外承認（アカウントごとに "approval": "external" を指定）。すべての送信経路で上記のガードを適用したうえで、メールを送信する代わりに、完全に解決されたメッセージを ~/.mailbox-mcp/pending/<id>.json に書き込み、その ID をモデルに知らせます。どのツールからも、そのキューの一覧表示、編集、承認はできません。ターミナルで操作します：mailbox-mcp pending、mailbox-mcp show <id>、mailbox-mcp approve <id>、mailbox-mcp reject <id>。approve はメッセージ全文を表示し、/dev/tty から確認を読み取ります（stdin ではないため、パイプでは渡せません）。その後、許可リストと 1 日の上限を再チェックし、添付ファイルを再読み込みして、変更があれば拒否したうえで、表示した内容をそのまま送信します。エージェントのシェルと同様に、制御端末のないシェルでは /dev/tty を開けないため、自身の送信を承認できません。エントリは 7 日後に期限切れになります。キューに入った送信の承認を参照してください。

ツールプロファイル（MAILBOX_MCP_PROFILE）。read では読み取り専用ツールのみが公開されます。draft では、アカウントからメールを送信できるツールを除くすべてのツールが公開されます。非表示のツールはツール一覧に含まれず、呼び出された場合も拒否されます。読み込むツールの選択を参照してください。

信頼できない内容の読み取り後にロック（アカウントごとに "untrustedReadLock": "approval" | "refuse" を指定）。ツールが、信頼できると確認できないメッセージをモデルに表示した場合、またはメッセージ内容をディスクにエクスポートまたはダウンロードした場合、その時点からサーバープロセスの終了までアカウントにロックがかかります。approval の場合、approval が設定されていなくても、そのアカウントからの送信はすべて保留キューに送られます。refuse の場合、サーバーが再起動されるまで送信は拒否されます。モデルが渡せる引数によってロックを解除することはできません。このロックが厳格なのは意図的です。メッセージの送信者が accounts.json のアカウントの trustedSenders リストに含まれ、かつ受信側サーバーの From ドメインに対する DMARC チェックに合格した場合に限り、メッセージは信頼できるものと見なされます。送信者やモデルが操作できるものは、信頼の判定に一切影響しません。From ヘッダー、Sent フォルダー、送信ログ、メールボックス検索のいずれも該当しません。trustedSenders が設定されていない場合、第三者からのメールを読むとすべて信頼できないものと見なされます。これは意図したデフォルトの動作です。多くの場合、長い信頼リストを設定するよりも、approval: "external" を使うのが適切です。ロックの判定方法を参照してください。 これによってプロンプトインジェクションが不可能になるわけではありません。モデルは依然として、望まない返信をするよう誘導される可能性があり、text/plain パートに、人間が目にする HTML パートとは異なる内容が記載されていることもあります。送信は人間が承認するようにしてください。妥当な設定例としては、検索のみが必要なアカウントでは readOnly: true または MAILBOX_MCP_PROFILE=read を設定し、エージェントが無人で送信するアカウントでは approval: "external" または許可リストを設定し、受信トレイの振り分けを行うものには untrustedReadLock を設定し、それ以外のすべてではデフォルトの確認を有効にしておく方法があります。

クイックスタート

インストール

Claude Code の MCP 設定ファイル（~/.claude.json）に追加します。パッケージは npx を使って npm から直接実行できます。

{
  "mcpServers": {
    "mailbox": {
      "command": "npx",
      "args": ["-y", "mailbox-mcp"],
      "env": {
        "MAILBOX_MCP_PASSPHRASE": "a-long-random-passphrase"
      }
    }
  }
}

MAILBOX_MCP_PASSPHRASE は、IMAP/JMAP の認証情報を保存時に暗号化するためのパスフレーズです。IMAP または JMAP アカウントを追加する前に設定する必要があり、Gmail のみを使う場合は不要です。MAILBOX_MCP_CONFIG_DIR を設定すると、設定ディレクトリを ~/.mailbox-mcp 以外の場所に変更できます。

git clone https://github.com/jgalea/mailbox-mcp.git
cd mailbox-mcp
npm install && npm run build

Gmail アカウントを追加する

1. Google Cloud プロジェクトを作成する

1. Google Cloud Console にアクセスして、新しいプロジェクトを作成します
2. Gmail API を有効にします：API とサービス > ライブラリ > Gmail API > 有効にする

2. OAuth 同意画面を設定する

1. Google Auth Platform > Branding にアクセスします
2. アプリ名 と ユーザーサポートメール を設定します
3. Audience に移動し、External を選択します
4. サインインに使う Google アカウントをテストユーザーとして追加します（認証に使用する正確な @gmail.com アドレスを指定してください。Workspace のエイリアスは使用できません）

3. OAuth 認証情報を作成する

1. Google Auth Platform > Clients に移動し、［クライアントを作成］をクリックします
2. アプリケーションの種類：デスクトップアプリ
3. ［作成］をクリックします
4. API とサービス > 認証情報 に移動し、作成したクライアントを見つけて、ダウンロードアイコンをクリックして JSON を取得します
5. ファイルを ~/.mailbox-mcp/oauth-keys.json として保存します

4. 認証する

Claude Code で次を実行します：authenticate alias="personal" provider="gmail" email="[email protected]"

ブラウザーウィンドウが開き、OAuth フローを完了できます。トークンは ~/.mailbox-mcp/accounts/ にローカル保存されます。

IMAP アカウントを追加する

Claude Code で次を実行します：

authenticate alias="work" provider="imap" email="[email protected]" host="imap.company.com" smtpHost="smtp.company.com" username="[email protected]" password="<app-password>"

認証情報は AES-256-GCM を使って保存時に暗号化されます。

JMAP アカウントを追加する

Claude Code で次を実行します：

authenticate alias="fastmail" provider="jmap" email="[email protected]" host="fastmail.com" username="[email protected]" password="<app-password>"

JMAP は .well-known/jmap 経由で API エンドポイントを自動検出します。認証情報は AES-256-GCM を使って保存時に暗号化されます。

対応する JMAP サーバー： Fastmail、Stalwart、Topicbox、Cyrus IMAP、および RFC 8620 に準拠するサーバー。

IMAP と比べた JMAP の利点：

• ネイティブなスレッド対応（合成ではない実際の会話）
• サーバー側での検索（より高速で正確）
• 1 回の HTTP リクエストでの一括操作
• 持続的な接続が不要

ツール

共通（Gmail + IMAP + JMAP）

Gmail 専用

アカウントの安全設定

~/.mailbox-mcp/accounts.json の各エントリには、次の8つのオプションフィールドを指定できます。

{
  "accounts": {
    "archive": { "provider": "gmail", "email": "[email protected]", "readOnly": true },
    "agent": {
      "provider": "imap", "email": "[email protected]",
      "host": "imap.example.com", "port": 993, "smtpHost": "smtp.example.com", "smtpPort": 587,
      "allowedRecipients": ["[email protected]", "@example.com"],
      "dailySendLimit": 20
    },
    "personal": { "provider": "gmail", "email": "[email protected]", "draftsOnly": true },
    "work": { "provider": "gmail", "email": "[email protected]", "approval": "external", "untrustedReadLock": "approval" },
    "triage": { "provider": "gmail", "email": "[email protected]", "untrustedReadLock": "refuse", "trustedSenders": ["[email protected]", "@partner.example"] }
  }
}

アカウント作成時に、同じ設定を authenticate に read_only、drafts_only、allowed_recipients、daily_send_limit、approval、untrusted_read_lock として渡すこともでき、list_accounts で確認できます。意図的に、これらを後から変更するツールは用意されていません。ファイルを編集してサーバーを再起動してください。不正なエントリがある場合、ガードなしで起動するのではなく、サーバーは起動を拒否します。

キューに入れた送信を承認する

サーバーの実行に使うバイナリが、承認 CLI も兼ねています。引数なしで実行すると MCP サーバーが起動し、コマンドを指定するとキューを処理して終了します。

mailbox-mcp pending        # id, account, from, recipients, subject, created, attachment names
mailbox-mcp show <id>      # the full message
mailbox-mcp approve <id>   # prints the message, asks "Type yes to send", sends exactly that
mailbox-mcp reject <id>    # drops it

npx でインストールした場合は、npx mailbox-mcp pending などを実行してください。設定ディレクトリはサーバーが使うものと同じです（MAILBOX_MCP_CONFIG_DIR、デフォルトは ~/.mailbox-mcp）。変更した場合は、同じ方法で設定してください。

approve は確認を /dev/tty から読み取り、標準入力からは読み取りません。開けない場合は、明確なエラーを表示して処理を拒否します。これにより、シェルにアクセスできるエージェントが自分の送信を承認できないようになっています。エージェントのシェルには制御端末がないためです。表示内容は送信内容そのものです。エントリーはシンボリックリンクを拒否するファイルディスクリプターを通じて一度だけメモリに読み込まれ、送信直前にファイルのハッシュが再確認されます。ターミナルエスケープ、双方向テキスト制御文字、ゼロ幅文字を含むメッセージは、画面上の表示が送信内容と異なる可能性があるため、無条件に拒否されます。承認時には、最新の accounts.json に基づいて許可リストと1日あたりの上限を再確認し、キューに入れた時点で記録されたパスからすべての添付ファイルを読み込みます。ファイルがなくなっているか、サイズが変わっている場合は拒否します。ほかの送信と同様に sends.jsonl に送信を記録し、保留中のファイルを削除します。7日を超えたエントリーは拒否されます。整理するには、拒否してください。保留ディレクトリは 0700、ファイルは 0600 で作成されます。

返信と転送では、キューに入る本文は入力したテキストです。show の説明どおり、スレッドのヘッダーと元の転送内容は送信時にプロバイダーが追加します。send_draft の場合、キューには下書き ID、宛先、および下書きの状態を示すフィンガープリントが保存されます。キューに入れた後で下書きや宛先が変更されていると、approve は拒否します。これにより、キューに入れた後に update_draft で変更して、以前の確認を利用することはできません。本文はメールクライアントで確認してください。

エージェントが Claude Code 内で動作する場合は、権限確認のプロンプトに承認コマンドが表示されないよう、.claude/settings.json の拒否リストに追加してください。

{ "permissions": { "deny": ["Bash(mailbox-mcp approve*)", "Bash(npx mailbox-mcp approve*)"] } }

「新しい宛先」の判定方法：このサーバーがそのアカウントから過去に送信したことがあるアドレス（sends.jsonl のログ）、アカウント自身のアドレス、またはプロバイダー検索（from:addr OR to:addr、結果は1件まで。IMAP では INBOX のみ）でメッセージが見つかったアドレスは、既知のアドレスです。それ以外のアドレスには confirm_new_recipient: true が必要です。返信先のメッセージから取得した宛先は、すでにその相手からメールを受信しているため、信頼済みとして扱われます。

authenticate は、安全設定の有無にかかわらず、すでに存在するエイリアスを拒否します。これにより、セッション中にアドレス、プロバイダー、ホストが差し替えられるのを防ぎます。reauth は設定に触れずに Gmail トークンを更新します。remove_account は、安全設定があるアカウントの削除を拒否します。削除して再追加すると、その設定が失われるためです。どちらの設定も accounts.json を参照します。また、モデルから呼び出せる機能は、設定ディレクトリやログディレクトリへの書き込みもできません。export_email、export_thread、download_attachment は、save_to がこれらのディレクトリ内を指す場合に拒否します（そのディレクトリが /tmp の下にある場合、大小文字を区別しないファイルシステムで大文字・小文字を変えて指定した場合、またはシンボリックリンクをたどって到達した場合も同様です）。検証済みの正規ディレクトリにのみ書き込み、ディレクトリが存在するようになってから再確認し、ファイル名の下に置かれたシンボリックリンクをたどって書き込むこともありません。送信の attachments も、同じ規則に従ってこれらのディレクトリからの読み込みを拒否します。これにより、承認キュー、accounts.json、送信ログ、保存された認証情報にはアクセスできない状態が保たれます。送信の宛先はすべて単一のアドレスでなければなりません。2つのアドレスを含む値は、最初のアドレスだけを確認するのではなく、拒否されます。

ロックの判定方法

untrustedReadLock は、次の条件をすべて満たす場合にのみメッセージを信頼済みとして扱います。From ヘッダーを解析した結果、プレーンなアドレスがちょうど 1 つだけであること（複数のアドレス、独自の山かっこや @ を含む表示名、不可視文字、アドレスがない場合は失敗します）。そのアドレスが、アカウントの trustedSenders のエントリー（アドレス全体、または @domain。サブドメインではなくドメインのみ）と一致すること。最上位の Authentication-Results ヘッダーがアカウント自身のサーバーによって記述されていること（authserv-id が authservId と一致すること。Gmail の場合は mx.google.com）。さらに、dmarc= の結果がちょうど 1 つ含まれ、その結果が pass であり、header.from が From のドメインと一致すること。それ以外はすべて信頼性を損ないます。リストにない送信者、メールが DMARC に合格しなかったリスト内の送信者（リストに登録されていない場合のアカウント自身のアドレスを含む）、authservId で指定していないサーバーからのメール、メッセージのヘッダーを提供できないツール、判定中に発生したエラーが該当します。Sent フォルダー、ローカルの送信ログ、メールボックス検索は判定に関与しません。ラベルやフォルダーはツール呼び出しで変更でき、検索には細工されたメッセージが混入する可能性があるためです。コンテンツがフェンスの外に出るため、エクスポートとダウンロードは無条件に信頼性を損ないます。

読み込むツールを選ぶ

すべての定義をコンテキストに読み込むクライアントでは、49 個のツールスキーマにおよそ 6,000 トークンを要します。日常的な使用では、ひと握りのツールで作業の大半をこなせるため、MAILBOX_MCP_TOOLS（カンマ区切り）を使って必要なグループだけを公開できます。未設定の場合は、すべてが読み込まれます。

"env": {
  "MAILBOX_MCP_TOOLS": "core,attachments"
}

無効なグループのツールを呼び出すと、有効にすべきグループ名を示すエラーが返されます。

ツールプロファイル

MAILBOX_MCP_PROFILE で、インスタンスの種類を選択します。MAILBOX_MCP_TOOLS と組み合わせて適用され、どちらでも許可されている場合にのみツールが読み込まれます。非表示のツールはツール一覧に表示されず、呼び出しても拒否されます。その際、プロファイル名を示すエラーが返されます。不明な値を指定すると、サーバーは起動時に停止します。

draft では、アカウントからメールを送信したり、今後第三者に送るメールの内容を変更したりする可能性があるため、次のツールを非表示にします。send_email、reply_email、forward_email、send_draft、send_template（メールを送信します）、create_filter（Gmail のフィルターはメールを転送したり、自動で振り分けたりできます）、set_vacation（自動返信を送信します）、set_signature（今後送信するすべてのメッセージに挿入されるテキストです）、unsubscribe と bulk_unsubscribe（攻撃者が指定した登録解除先を提示し、操作させる可能性があります）。下書き、ラベル、アーカイブ、ゴミ箱、取り消し機能付き一括操作、ダウンロード、エクスポートは、すべて引き続き利用できます。

"env": { "MAILBOX_MCP_PROFILE": "draft", "MAILBOX_MCP_TOOLS": "core,attachments" }

Jev による受信トレイのトリアージ（任意）

TypeSafe で取得したキーを MAILBOX_MCP_TYPESAFE_API_KEY（または TYPESAFE_API_KEY）に設定すると、inbox_summary が最近の各メッセージに「返信が必要」「参考情報」「ニュースレター」「領収書」「通知」「不審」のラベルを付けます。また、送信者が約1日以内に何かを必要としている場合は「緊急」とし、信頼度も表示します。

"env": { "MAILBOX_MCP_TYPESAFE_API_KEY": "your-key" }

Jev は判断モデルです。上記の固定オプションからしか選べないため、メール内のテキストによって別の動作をさせることはできません。ラベルはメールのテキストではなく、これらの固定オプションから付与され、信頼できないコンテンツのフェンスの外側に表示されます。

各メッセージの送信者、件名、スニペット（最大2,000文字）を TypeSafe の API に送信します。キーを設定しなければ、何も送信されず、ツールはこれまでとまったく同じように動作します。1回の呼び出しで最大25件のメッセージをトリアージします。処理に失敗したメッセージは推測せず、未分類として報告されます。

添付ファイルの送信

send_email、reply_email、forward_email、create_draft は、省略可能な attachments パラメーターを受け付けます。これはローカルファイルパスの配列です。サーバーは各ファイルを読み込み、拡張子から MIME タイプを判定して、送信メッセージ（または下書き）に埋め込みます。

send_email account="personal" to=["[email protected]"] subject="The report" body="See attached." attachments=["/path/to/report.pdf", "/path/to/chart.png"]

• 各ファイルは通常のファイルで、サイズは25 MB以下である必要があります。メッセージ全体の上限は25 MBです（Gmail の厳格な上限）。
• パスはシンボリックリンクをたどって解決され、ヘッダーに入れる前にファイル名から CRLF が取り除かれます。
• Gmail では、添付ファイル付きのメッセージは JSON エンドポイントではなく、マルチパートアップロードエンドポイント（API 上限は35 MB）経由で送信されるため、実際の上限はメッセージの25 MBです。
• JMAP では、各ファイルをまずサーバーのアップロード URL にアップロードし、その後 Email/set 呼び出しで生成された blobIds を参照します。

送信者アドレスの選択

1つのアカウントが複数のアドレスを使い分けることはよくあります。send_email、reply_email、forward_email、create_draft、update_draft は、省略可能な from パラメーターを受け付けます。指定しない場合は、アカウントのメインアドレスが使用されます。

reply_email account="personal" message_id="18f..." from="[email protected]" body="Thanks, sorted."

指定できる形式は [email protected] と Name <[email protected]> です。照合では大文字と小文字は区別されません。

送信前にアカウントとの照合が行われ、一致しない場合は使用可能なアドレスの一覧を示して呼び出しが失敗します。これは重要です。Gmail は、From ヘッダーに指定されたアドレスが未確認の場合、メインアドレスにひそかにフォールバックします。そのため、誤ったアドレスからメッセージが送信されても、成功したように見えることがあります。たとえば Amazon のカスタマーサービスなど、一部の宛先は、登録済みのアドレス以外から送信されたメールを拒否します。

• Gmail：アドレスは確認が完了した送信元エイリアスである必要があります。list_send_as を実行すると確認できます。確認待ちのエイリアスは拒否されます。
• JMAP：アドレスはアカウントの ID のいずれかと一致する必要があります。送信時にその identityId が付与されます。
• IMAP：照合対象となるエイリアス一覧がないため、任意の from が SMTP リレーに渡され、送信時に受け付けるか拒否されます。

ライセンス

MIT

AgentVania で開発されました。