Apple Mail MCP

Apple Mail MCP

本文を網羅的に検索できる唯一の Apple Mail MCP サーバーです。AppleScript ベースのサーバーがタイムアウトする大容量メールボックスでも、確実に検索できます。メールの閲覧、検索、コンテンツの抽出に使える 8 つのツールを備えています。

詳しいガイドは ドキュメントをご覧ください。

クイックスタート

Claude Code（プラグイン）

claude plugin marketplace add imdinu/apple-mail-mcp
claude plugin install apple-mail@imdinu

Claude Desktop（ワンクリックバンドル）

最新リリース から apple-mail-mcp-<version>.mcpb をダウンロードし、 ダブルクリックしてください。

プラグインとバンドルはどちらも、薄いランチャー（利用可能なものに応じて uvx → pipx → プライベート venv）を介してリリース済みの PyPI パッケージを実行します。コードの同梱はなく、手動インストールと同じ動作です。サーバーは --watch を指定して起動します。インデックスを最新の状態に保つため、起動アプリ（Claude Code／Claude Desktop）にフルディスクアクセスを許可してください。

任意の MCP クライアント

pipx install apple-mail-mcp

MCP クライアントに次の内容を追加してください。

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

検索インデックスを構築する（推奨）

# Requires Full Disk Access for Terminal
# System Settings → Privacy & Security → Full Disk Access → Add Terminal

apple-mail-mcp index --verbose

設定（任意）

apple-mail-mcp init   # writes ~/.apple-mail-mcp/config.toml

編集可能なコメント付き設定ファイルを書き込み、メインのアカウントやメールボックスなどのデフォルトを設定できます。環境変数で設定する場合は、すべてのキーに対応する APPLE_MAIL_* 環境変数を使用できます。スキーマと優先順位のルールについては、設定をご覧ください。

ツール

ツール	目的
list_accounts()	メールアカウントを一覧表示
list_mailboxes(account?)	メールボックスを一覧表示
get_emails(filter?, limit?)	メールを取得 — すべて、未読、フラグ付き、今日、過去 7 日間
get_email(message_id)	本文全体と添付ファイルを含むメールを 1 件取得
search(query, scope?, before?, after?, highlight?)	検索 — すべて、件名、送信者、本文、添付ファイル
get_email_links(message_id)	メールからリンクを抽出
get_email_attachment(message_id, filename)	添付ファイルの内容を抽出
get_attachment(message_id, filename)	非推奨 — get_email_attachment() を使用

パフォーマンス

実際の 約 73K 件のメッセージがあるメールボックスで、ほかの 6 つの Apple Mail MCP サーバーと比較テストを実施しました。

• 本文を網羅的に検索できる唯一のサーバーです。 ほとんどの競合製品は本文検索に対応していません。対応している唯一の製品（BastianZim）も、直近の 5000 件のみをリアルタイムでスキャンするため、それより古いメッセージは検索されないままです。このサーバーの FTS5 インデックスはメールボックス全体を対象とします。
• ディスク優先の .emlx 読み込みにより、メール 1 件を 約 3 ミリ秒で取得します（JXA の往復処理は不要です）。
• Envelope-Index の SQLite を直接読み取ることで（0.4+）、list_accounts は 約 1 ミリ秒、メール 50 件の一覧表示は 約 5 ミリ秒です。BastianZim／rusty／pl-lyfx と同じ読み取り経路を使い、正確性を確保するためのフォールバックとして JXA を使用します。
• FTS5 による件名検索は 約 7 ミリ秒で、同じ処理におけるネイティブ Rust と競合できる速度です。
• 73K 件のメールボックスで、ベンチマーク対象の全 6 項目において安定して動作します。AppleScript ベースのサーバーはタイムアウトしたり、構文エラーを発生させたり、未対応の処理をスキップしたりします。

設定

Apple Mail MCP は、そのまま利用できます。デフォルトをカスタマイズするには、apple-mail-mcp init を実行して config.toml テンプレートを生成するか、対応する APPLE_MAIL_* 環境変数を使用してください。完全なスキーマと、CLI > 環境変数 > ファイル > デフォルトの優先順位については、設定ドキュメントをご覧ください。

MCP クライアントの起動設定を使ったクライアントごとの環境変数の上書きにも対応しています。

{
  "mcpServers": {
    "mail": {
      "command": "apple-mail-mcp",
      "args": ["--watch"],
      "env": {
        "APPLE_MAIL_DEFAULT_ACCOUNT": "Work"
      }
    }
  }
}

CLI の使い方

すべてのツールは、スタンドアロンの CLI コマンドとしても利用できます（MCP サーバーは不要です）。

apple-mail-mcp search "quarterly report" --scope subject
apple-mail-mcp search "invoice" --after 2026-01-01 --limit 10
apple-mail-mcp read 12345
apple-mail-mcp emails --filter unread --limit 10
apple-mail-mcp accounts
apple-mail-mcp mailboxes --account Work
apple-mail-mcp extract 12345 invoice.pdf

すべてのコマンドは JSON を出力します。CLI ベースでアクセスするための Claude Code スキルを生成できます。

apple-mail-mcp integrate claude > ~/.claude/skills/apple-mail.md

開発

git clone https://github.com/imdinu/apple-mail-mcp
cd apple-mail-mcp
uv sync
uv run ruff check src/
uv run pytest

ライセンス

GPL-3.0-or-later