Apple Mail

apple-mail-mcp

AI アシスタントが Apple Mail のメールを検索して読める、読み取り専用のMCP サーバーです。

macOS 専用です。 Mac 上で Mail.app が保持しているローカルインデックスを読み取ります。

claude mcp add apple-mail -- npx -y @redpop/apple-mail-mcp

次に、npx -y @redpop/apple-mail-mcp setup を実行して、フルディスクアクセスを一度だけ許可します。Claude Desktop 向けにはワンクリックでインストールできるバンドルがあります。インストールを参照してください。

できること

主な用途は、「X についてのメールを探す」ことです。

"Find the mail from the landlord about the heating bill"
"What did Anna send me last week with an attachment?"
"Show the whole thread about the contract renewal"

4 つのツール、list_mailboxes、search_messages、get_message、get_thread を提供します。検索対象は、送信者、受信者、件名、フリーテキスト、メールボックス、日付範囲、未読、フラグ付き、添付ファイルです。また、メッセージ本文も検索できます。結果には、Mail.app でメールを開く message:// リンクが含まれます。リンク先では Mail によって Message-ID が保存されます（macOS 15 を除く）。詳細は docs/tools.md を参照してください。

このツールの特長

• 高速です。 AppleScript で Mail.app を操作する代わりに、Mail の SQLite インデックスを検索します。実際のメールボックス（メッセージ行が約 240,000 件）では、検索結果の 1 ページ分をヘルパーが取得するのに 4～90 ms、件名検索は 2 回目以降 25 ms かかります。測定値とその制限については、docs/architecture.md を参照してください。
• フルディスクアクセスが許可されるのは小さなヘルパーだけで、ターミナルや AI クライアントには許可されません。 サーバーは「Mail MCP Helper」という小さなアプリを介して Mail のファイルにアクセスし、macOS はそのアプリのみにアクセス許可を結び付けます。Node、Terminal、Claude に許可されることはありません。
• フラグで読み取り専用にするのではなく、設計上、読み取り専用です。 メールの送信、下書き作成、移動、削除、フラグ設定を行うコードはありません。データベースを書き込み用に開いたり、ネットワーク接続を開いたりするコードもありません。
• Mail.app を起動しておく必要はなく、Automation の確認も表示されません。 ただし、データが最新になるのは Mail の最後の同期までです。また、Mail がダウンロードしていないメッセージには本文がありません。
• スレッドとディープリンクに対応しています。 get_thread は会話を返します。メッセージには message:// リンクが含まれます（macOS 15 を除く）。
• セキュリティ関連のメールは、デフォルトで内容が隠されます。 認証コード、パスワードのリセット、サインインリンクのように見えるメッセージは、本文を表示せず、件名中の数字をマスクし、本文検索の対象から除外します。検出はベストエフォートであり、保証されるものではありません。
• 設定はツールのパラメーターではなく、常に構成から取得されます。 そのため、悪意のあるメールによってモデルに設定を無効化させることはできません。
• apple-calendar-mcp と連携できます。 「木曜日の会議についてのメールを探す」といった使い方ができます。タイムスタンプはオフセット付き ISO 8601 形式、エラーは各エラーコードにつき平易な英語の文を 1 つ含む isError 結果として返すなど、同じ規約を採用しています。

要件

• macOS 15 以降。実際のメールボックスでの検証は macOS 27.0.1、Mail 16.0 のみです。macOS 15.8 と 26.6 のデータベース構造は、メールアカウントのないランナーで確認したところ、ヘルパーのカラムチェックに合格しています。macOS 15 では Mail に Message-ID ヘッダーが保存されないため、結果に message:// リンクは含まれません。対応状況はバージョン番号ではなく Mail のデータベース構造に依存します。doctor で確認できます。 ほかのバージョンからの報告も歓迎します。問題の報告を参照してください。
• 22 系列では Node.js 22.16 以降、または 24 以降。
• 少なくとも 1 つのアカウントで Mail が設定されていること。
• Exchange アカウントは未テストです。メールボックスとメッセージのメタデータは一覧表示されますが、Exchange メールの本文はまだ読み取れません。get_message は file_not_found を返します。docs/exchange.md を参照してください。

セキュリティモデルの概要

メールボックスには、コード、パスワード再設定リンク、契約書などの秘密情報が含まれています。インターネットにもアクセスできるモデルに接続する前に、以下をお読みください。

• ヘルパーにはフルディスクアクセス権が付与され、固定されたコマンドのみを実行します。自由形式の SQL やパスパラメーターはなく、メールの内容を解析することもありません。信頼できない MIME の解析は、特別な権限を持たない Node で行います。
• メール本文は信頼できない入力です。サーバーはモデルにそのことを伝えますが、モデルに強制することはできません。
• クライアントにウェブツールや送信ツールもある場合、悪意のあるメールによって、モデルが読み取った内容を漏えいさせようとする可能性があります。これらのツールで確認を必須にするか、それらのツールを備えていないクライアントでこのサーバーを使用してください。
• ユーザーとして実行されているプログラムは、どれもヘルパーを起動し、それを使ってメールを読むことができます。ターミナルにフルディスクアクセス権を与えるよりはリスクが低いものの、リスクがないわけではありません。
• オプションの本文インデックスは、フルディスクアクセス権がなくても、同じユーザーのプログラムならどれでも読み取れる、メールのプレーンテキストコピーです。既定ではオフです。本文インデックスをご覧ください。

脅威モデルの詳細と、残存する2つのリスクについては、SECURITY.mdをご覧ください。

インストール

Claude Code および Cowork（プラグインとして）（ダイアログで設定し、リリースごとに更新）：

/plugin install apple-mail-mcp --marketplace redpop/apple-mail-mcp

プラグインは、プラグインのバージョンに対応する以下の npm パッケージを実行します。npx -y @redpop/apple-mail-mcp setup を使って、フルディスクアクセス権を一度付与してください。

Claude Code（プラグインなし）（またはコマンドを起動する任意のクライアント）：

claude mcp add apple-mail -- npx -y @redpop/apple-mail-mcp
npx -y @redpop/apple-mail-mcp setup

setup がフルディスクアクセス権の付与を案内します。設定は環境変数で行います。設定をご覧ください。

Claude Desktop： 最新リリースから apple-mail-mcp-<version>.mcpb をダウンロードして開いてください。Claude Desktop が拡張機能をインストールし、設定ページを表示します。ここでの設定項目は環境変数と同じです。アクセス権がない状態で初めてツールを呼び出すと、「システム設定」と権限付与用の Finder ウィンドウが開きます。

各リリースには SHA256SUMS が含まれ、バンドルとヘルパーの zip ファイルについてビルド来歴の証明が付属します。

ソースからインストール

開発用、または未リリースの変更を実行する場合に使用します。Swift 用の Xcode Command Line Tools と、再ビルド後も権限を維持するための Apple Development 証明書がキーチェーンに必要です。証明書がない場合、ビルドはアドホック署名となり、独自の、より弱い識別情報が割り当てられます。

git clone https://github.com/redpop/apple-mail-mcp.git
cd apple-mail-mcp
npm ci
npm run build           # TypeScript -> dist/
npm run build:helper    # Swift helper -> bin/Mail MCP Helper (Dev).app

次に、ヘルパーにフルディスクアクセス権を付与し（次のセクションを参照）、サーバーを登録します。

claude mcp add apple-mail \
  -e APPLE_MAIL_HELPER_PATH="$PWD/bin/Mail MCP Helper (Dev).app" \
  -- node "$PWD/dist/index.js"

APPLE_MAIL_HELPER_PATH は、サーバーにローカルビルドの場所を指定します。指定しない場合、サーバーはパッケージ内のリリースバンドル Mail MCP Helper.app を探します。このバンドルを生成するのはリリースパイプラインのみです。ローカルビルドの名前は「Mail MCP Helper (Dev)」（Apple Development 署名）または「Mail MCP Helper (Ad hoc)」（証明書なし）です。どちらも独自のバンドル ID を使用するため、リリースアプリの権限に影響することはありません。

ビルドスクリプトは、CI の外部で Developer ID 証明書を使って署名することはありません。

フルディスクアクセスを許可する

macOS は ~/Library/Mail を保護しており、アクセス許可を求めるダイアログは表示されません。ヘルパーアプリに対して、アクセスを一度だけ許可します。

1. setup を実行します（ソースからの場合：APPLE_MAIL_HELPER_PATH="$PWD/bin/Mail MCP Helper (Dev).app" node dist/index.js setup、npm からの場合：npx -y @redpop/apple-mail-mcp setup）。「システム設定」の「プライバシーとセキュリティ」＞「フルディスクアクセス」が開き、Finder にヘルパーが表示され、アクセスが機能するまで待機します。
2. Finder のウインドウから Mail MCP Helper をリストにドラッグし、スイッチをオンにします。（ローカルビルドの場合、名前は「Mail MCP Helper (Dev)」です。）または、＋をクリックして Cmd-Shift-G を押し、setup が出力するパスを貼り付けます。
3. setup が成功を報告し、Claude Code にサーバーを追加するコマンドを出力します。

ターミナルを使わない場合（たとえば MCPB バンドルを使う場合）は、許可が拒否されたとき、最初のツール呼び出しで「システム設定」と Finder のウインドウが自動的に開きます。これはサーバープロセスごとに一度だけ行われ、エラーメッセージには同じ手順が表示されます。

注：

• 許可はアプリのバンドル ID に紐づいており、場所には紐づいていません。パッケージを移動したり更新したりしても、再度許可する必要はありません。
• 「Mail MCP Helper」がリストにあり、スイッチがオンなのにアクセスが拒否される場合、その項目は古くなっています。マイナスボタンで削除し、もう一度追加してください。
• 許可した後に再起動する必要はありません。

その他のケースについては、docs/troubleshooting.md を参照してください。

設定

これらの値は、たとえば claude mcp add -e NAME=value を使ってサーバーの環境変数に設定します。ツールのパラメーターから変更することはできません。ブール値には true、false、1、0 を指定できます。空の値は未設定として扱われます。値が無効でもサーバーは停止しませんが、その後のすべてのツール呼び出しは設定名を示す CONFIG_INVALID エラーで失敗し、「すべて許可」にフォールバックすることはありません。

サーバーは起動時にこれらの設定を一度だけ読み込みます。設定を変更した後は、クライアントを再起動してください。Claude Desktop では、アプリを終了（Cmd-Q）してから再度開きます。拡張機能をオフにしてからオンにしたり、設定を保存したりしても、実行中のサーバーと以前の設定がそのまま維持されます。

変数	デフォルト	意味
APPLE_MAIL_ACCOUNTS	空（すべてのアカウント）	許可するアカウントをカンマ区切りで指定します。大文字と小文字を区別せず、アカウントの UUID、アドレス、または名前に一致します。2 つのアカウントで同じ名前が使われている場合は両方に一致します。片方を選ぶには、アドレスまたは UUID を使用してください。
APPLE_MAIL_INCLUDE_JUNK	false	迷惑メールの役割を持つメールボックスとそのサブフォルダーを含めます。
APPLE_MAIL_INCLUDE_TRASH	false	ゴミ箱の役割を持つメールボックスとそのサブフォルダーを含めます。
APPLE_MAIL_EXCLUDE_MAILBOXES	空	非表示にするメールボックスをカンマ区切りで指定します。メールボックス名（完全一致、大文字と小文字は区別しない）または / を含むパスに一致します。
APPLE_MAIL_SHOW_SECURITY_MAILS	false	セキュリティメールと判定されたメッセージについて、本文を除外したり件名をマスキングしたりせずに表示します。
APPLE_MAIL_BODY_SEARCH	true	search_messages で bodyContains を使用できるようにします。false の場合、これを使うと INVALID_INPUT エラーになります。
APPLE_MAIL_BODY_INDEX	false	メッセージ本文の全文検索インデックスをディスク上に作成し、bodyContains ですべてのメッセージを検索できるようにします。APPLE_MAIL_BODY_SEARCH が有効な場合にのみ反映されます。オフにすると、次回の起動時にインデックスが削除されます。
APPLE_MAIL_MAX_RESULTS	50	検索の limit の上限（1～100）です。
APPLE_MAIL_MAX_BODY_CHARS	20000	get_message の maxChars の上限（1000～100000）です。
APPLE_MAIL_HELPER_PATH	未設定	開発専用：ヘルパーバンドル（Dev または Ad hoc）へのパスです。リリース版のバンドル ID を持つバンドルは拒否されます。
APPLE_MAIL_MCP_DEBUG	false	ヘルパーへのリクエストごとに、コマンド、所要時間、結果コードを 1 行ずつ stderr に書き込みます。例：apple-mail-mcp: search 42 ms ok。ペイロードや結果は書き込みません。

例：仕事用アカウントのみを対象にし、Archive という名前のメールボックスを除外します。

claude mcp add apple-mail \
  -e [email protected] \
  -e APPLE_MAIL_EXCLUDE_MAILBOXES=Archive \
  -- npx -y @redpop/apple-mail-mcp

本文インデックス

インデックスがない場合、bodyContains は検索中にメッセージをデコードするため、1 回の呼び出しで確認できるのは最新の候補 2,000 件まで、または処理時間 3 秒までです。数年前のメールにたどり着くには、何ページも検索することがあります。APPLE_MAIL_BODY_INDEX=true を設定すると、サーバーはメッセージ本文の全文インデックスを保持し、スキャンと同じ一致結果、順序、matchContext で、1 回の呼び出しですべてを検索します。

• ディスク容量： メール 1 件あたり約 14 KiB です。テスト用メールボックスでは、121,000 件のメールで 1.7 GiB を使用しました。
• 構築時間： メール 1 件あたり約 3 ms で、120,000 件では 6 分弱です。サーバーは最初のツール呼び出しが正常に完了した後、バックグラウンドで構築を開始し、再起動後も続行します。ツール呼び出しが優先されます。
• 構築が完了するまで bodyContains は従来どおりスキャンし、note に進捗状況が表示されます。3 文字未満の検索語は常にスキャンされます。
• 自動的に最新の状態を維持します： 新しいメールは各本文検索の前と毎分追加され、削除されたメールは 30 分ごとに削除されます。設定の変更は次回起動時に適用されます。
• 保存場所： ~/Library/Application Support/apple-mail-mcp/body-index/。ディレクトリのアクセス権は 0700、ファイルは 0600 で、Time Machine の対象外です。再構築するには、このディレクトリを削除してください。
• 無効にすると、 次回のサーバー起動時にインデックスが削除されます。
• 必要条件： 22 系列の Node 22.16 以降、または Node 24 以降が必要です（FTS5 を使用する node:sqlite のため）。条件を満たさない場合、インデックスは無効のままになり、検索はライブデータをスキャンします。

doctor を実行すると、body-index の項目に状態が表示されます。インデックスはメール本文のコピーであり、フルディスクアクセスがなくても、同じユーザーのプログラムから読み取れます。有効にする前に SECURITY.md をお読みください。

ツール

ツール	機能
list_mailboxes	アカウントと表示可能なメールボックスを、合計件数、未読件数、役割（受信トレイ、送信済み、迷惑メールなど）とともに一覧表示します。
search_messages	送信者、受信者、件名、フリーテキスト、メールボックス、日付、未読、フラグ付き、添付ファイル、および任意で本文テキストによる新しい順の検索を行います。カーソルを使用してページ分割されます。
get_message	1 件のメッセージを取得します。ヘッダー、添付ファイル名、プレーンテキストの本文を返し、引用された返信を任意で削除できます。
get_thread	1 つの会話のメッセージを、本文を含めずに古い順で取得します。

4 つすべて読み取り専用としてマークされています。パラメーター、結果、エラーコードについては、docs/tools.md をご覧ください。

診断とバグ報告

npx -y @redpop/apple-mail-mcp doctor        # from source: node dist/index.js doctor

doctor は、macOS のバージョン、ヘルパーの署名、フルディスクアクセス、データベースのレイアウト、ローカルファイルがあるメッセージの件数、メールボックスの役割、非表示になっている削除済みアカウントとメールがオフになっているアカウントの件数、有効な設定、本文インデックスの状態を確認します。デフォルトの出力には名前、アドレス、件名が含まれないため、そのまま issue に貼り付けられます。--verbose を付けるとメールボックス名とアカウント識別子が追加されます。--json は機械処理向けです。--schema はデータベースのフィンガープリント、不足している列があればその列、Mail のデータベースの CREATE TABLE 文のみを出力します（構造のみで、データは含みません）。終了コード 1 は、少なくとも 1 つのチェックに失敗したことを意味します。

問題の報告

https://github.com/redpop/apple-mail-mcp/issues で issue を作成し、doctor の出力を添付してください。macOS 27 以外のバージョンで実行している場合は、代わりに doctor --schema の出力を添えて スキーマレポート を作成してください。これは、こちらが得られる最も有用なレポートです。 セキュリティ上の問題は GitHub Security Advisories から報告してください。詳細は SECURITY.md をご覧ください。

その他のドキュメント

• docs/tools.md：各ツール、そのパラメーター、結果、エラー
• docs/architecture.md：仕組みと測定結果
• docs/troubleshooting.md：アクセス許可とデータベースに関する問題
• docs/exchange.md：Exchange アカウントについて判明していること
• SECURITY.md：脅威モデルと残存リスク
• docs/releasing.md：リリースのビルド、署名、公開方法（メンテナー向け）

意図的に含めていない機能

送信、返信、下書き、移動、削除、フラグ付け、添付ファイルの内容、セマンティック検索、 リンクの抽出。読み取り専用のサーバーのほうが安心して利用できます。

プライバシーポリシー

このポリシーは、npm、GitHub のリリース、および MCP Registry で公開されているサーバーとヘルパーアプリに適用されます。

収集する情報

作成者も、いかなるサービスも情報を収集しません。サーバーにはテレメトリー、アナリティクス、クラッシュレポート機能はなく、サーバーもヘルパーもネットワーク接続を開きません。

お使いの Mac では、サーバーはツールの実行に必要な情報を読み取ります。Mail のローカルインデックスと ~/Library/Mail 内のメッセージファイル、および ~/Library/Accounts/Accounts4.sqlite にあるメールアカウントの名前とユーザー名です。読み取る情報は設定によって制限されます（アカウント、迷惑メール、ゴミ箱、除外するメールボックス、セキュリティ関連のメール）。

情報の使用と保存方法

データは AI クライアントがツールを呼び出したときにのみ読み取られ、結果はそのクライアントにのみ返されます。サーバーは ~/Library/Application Support/apple-mail-mcp/（ディレクトリは 0700、ファイルは 0600）に、次の 2 種類のファイルを保存します。

• state.json：Mail へのアクセスが最後に成功した日時、およびヘルパーのバージョンとチェックサム。メールデータは含まれません。
• 本文インデックス。APPLE_MAIL_BODY_INDEX=true を設定した場合にのみ作成されます。設定によって表示対象となるメッセージの本文を全文コピーします。セキュリティ関連のメールは含みません。本文インデックスとSECURITY.mdを参照してください。

APPLE_MAIL_MCP_DEBUG=true を設定すると、サーバーはリクエストごとに、処理時間と件数を含む1行を標準エラー出力に書き込みます。メールの内容は含みません。その出力をログに保持するかどうかは、クライアントが決定します。

第三者との共有

サーバーは誰とも情報を共有しません。AI クライアントがツールの結果をどう扱うかについては、クライアントとモデルプロバイダーのプライバシーポリシーが適用されます。クラウドでホストされているモデルは、クライアントが送信した結果を受け取ります。npm または npx を通じてインストールまたは更新すると、npm の規約に基づき、npm レジストリからパッケージがダウンロードされます。

保持期間

state.json はその場で上書きされ、削除するまで残ります。本文インデックスは有効な間は最新の状態に保たれ、無効にした後、次回のサーバー起動時に削除されます。すべて削除するには、~/Library/Application Support/apple-mail-mcp/ を削除してください。サーバーが ~/Library/Mail 内のデータを変更または削除することはありません。

お問い合わせ

このポリシーに関する質問は、https://github.com/redpop/apple-mail-mcp/issues で issue を作成してください。セキュリティ上の問題は、SECURITY.mdの説明に従って非公開で報告してください。

ライセンス

MIT。LICENSEを参照してください。