Apple Mail MCP サーバー

Apple Mail へのプログラム的なアクセスを提供する MCP サーバーです。Claude などの AI アシスタントが macOS 上でメールの読み取り、送信、検索、管理を行えるようにします。

⚠️ 1.0 未満 — 破壊的変更が予想されます。 MCP ツールのインターフェース（ツール名、パラメータ、戻り値の形式）は、プロジェクトの成熟に伴い進化し続けています。特定のバージョン（例: apple-mail-mcp==0.10.2）に固定し、アップグレード前に CHANGELOG を確認してください。

ツール（29 個）

ライフサイクル別にグループ化（読み取り専用 10 個、変更操作 19 個）:

• 探索 — list_accounts、list_mailboxes、list_rules、list_templates: 設定されている内容を列挙します（外部キャッシュなし — アカウントごとに呼び出してください）。

• 読み取り — search_messages、get_messages、get_thread、get_attachment_content、get_template、render_template: メール・スレッドの読み取り、添付ファイルの内容のインライン取得、テンプレートのレンダリングを行います。

• メール操作 — update_message（既読・フラグ・移動を一度に実行）、delete_messages（→ ゴミ箱）、save_attachments（ディスクに保存、バイト数上限付き）。

• 下書き — create_draft（新規 / 返信 / 転送、オプションで send_now）、update_draft、delete_draft。

• 直接送信 — send_email、reply、reply_all、forward: 下書きを経由せず、1 回の呼び出しで送信します。各操作は実際に送信されます。Mail 内に 2 回目の確認ステップはありません。

• アカウント — delete_account: Mail.app から設定済みアカウントを削除します。

• メールボックス CRUD — create_mailbox、update_mailbox（名前変更または移動）、delete_mailbox。

• ルール — create_rule、update_rule、delete_rule。

• テンプレート（書き込み） — save_template、delete_template。

破壊的操作（delete_*、移動・転送・削除アクションを含む create_rule、send_now=true 付きの create_draft）は、MCP の確認要求（elicitation）を通じて確認を求めます。完全なパラメータと戻り値の形式については docs/reference/TOOLS.md を参照してください。

Related MCP server: apple-mail-mcp

前提条件

• macOS 10.15（Catalina）以降

• Python 3.10 以降

• 少なくとも 1 つのアカウントが設定された Apple Mail

• uv（推奨）または pip

インストール

# From source (recommended for development)
git clone https://github.com/LeChabrax/apple-mail-mcp.git
cd apple-mail-mcp
uv sync --dev

設定

Claude Desktop の設定ファイル（~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。uv sync はコンソールスクリプトを .venv/bin/apple-mail-mcp にインストールします。Claude Desktop にはその絶対パスを指定してください — Claude Desktop の制限付きスパウン環境では最も信頼性の高い形式です（uv が PATH にあることに依存しません）:

{
  "mcpServers": {
    "apple-mail": {
      "command": "/path/to/apple-mail-mcp/.venv/bin/apple-mail-mcp"
    }
  }
}

（uv 経由で実行したい場合の同等の代替案: "command": "uv", "args": ["--directory", "/path/to/apple-mail-mcp", "run", "apple-mail-mcp"]）

オプション: 読み取り / 書き込みサーバーの分割

Claude Desktop はツールごとに権限を確認します。10 個の読み取りツール（list / search / get）を一括承認しつつ、19 個の変更ツールを呼び出しごとに確認したい場合は、コネクタを 2 回実行します — 1 回は --read-only 付き、もう 1 回はなしで — 2 つの別々の mcpServers エントリとして:

{
  "mcpServers": {
    "apple-mail-read": {
      "command": "/path/to/apple-mail-mcp/.venv/bin/apple-mail-mcp",
      "args": ["--read-only"]
    },
    "apple-mail-write": {
      "command": "/path/to/apple-mail-mcp/.venv/bin/apple-mail-mcp"
    }
  }
}

--read-only サーバーは 10 個の読み取りツールのみを公開するため、Claude Desktop のサーバーごとの権限 UI が自然にそれらをグループ化します。フルサーバーは書き込みを個別に確認し続けます。トレードオフ: コネクタプロセスが 2 倍になります。ツールごとの分類と、将来の互換ホストが分割なしで同じ UX を提供するために使用できる MCP アノテーションヒント（readOnlyHint / destructiveHint / idempotentHint）に関する注記については、docs/reference/TOOLS.md を参照してください。

権限

初回実行時に、macOS が Automation アクセスを要求します。以下の場所で権限を付与してください: システム設定 > プライバシーとセキュリティ > 自動化 > ターミナル（または使用中の IDE）

オプション: IMAP による高速検索

search_messages は AppleScript 経由でそのまま動作します。大規模なメールボックス（数千件のメール）の場合、AppleScript の whose 句はクエリごとに 1〜5 秒かかることがあります。より高速なサーバーサイド検索が必要な場合は、アカウントごとに Keychain エントリを追加して IMAP 委任を有効にできます。

仕組み。 アカウントの認証情報が存在する場合、サーバーは IMAP（高速なサーバーサイド SEARCH）を使用します。それ以外の場合 — または IMAP が失敗した場合（オフライン、パスワード誤り、タイムアウト）— は、静かに AppleScript にフォールバックします。機能が失われることはありません。IMAP が設定され到達可能な場合にのみ速度が向上します。通常のオプトインは Keychain エントリ（下記）です。環境変数によるフォールバック（後述）は、Keychain が使用できないコンテキストをカバーします。

アカウントごとの 1 回限りのセットアップ。

1. プロバイダーでアプリ固有のパスワードを生成します。手順はプロバイダーによって異なります:

   • iCloud: appleid.apple.com/account/manage → App 固有のパスワード。Apple ID で 2FA が有効である必要があります（デフォルト）。

   • Gmail: myaccount.google.com/apppasswords。Google アカウントで 2 段階認証が有効である必要があります。

   • Yahoo / Fastmail / AOL: プロバイダーのアカウントセキュリティ設定でアプリパスワードを生成します。

2. setup-imap サブコマンドを実行します。パスワードをプロンプトで入力し（エコーなし）、Keychain エントリを書き込み、接続して検証します:

   apple-mail-mcp setup-imap --account iCloud

   Mail.app のアカウント名を正確に置き換えてください — Mail.app に表示されているラベル（例: iCloud、Gmail、"Yahoo!"）を使用します。CLI は:

   • Mail.app からアカウントのプライマリメールアドレスを検索します（--email で上書き可能。これは永続化され、ランタイムも同じログインを使用します — 下記の iCloud の癖を参照）、

   • getpass でプロンプトを表示するため、パスワードがシェル履歴に残ることはありません、

   • apple-mail-mcp.imap.<account> の Keychain に書き込みます（冪等 — 新しいパスワードで再実行すると既存のエントリが更新されます）、

   • IMAP 接続を開き、実際の LOGIN を実行してパスワードが機能することを確認します。拒否された場合は Keychain エントリをロールバックするため、壊れた項目を残さずに再試行できます。

3. 次の IMAP バックアップ呼び出しで「セキュリティが 'login' キーチェーンを使用しようとしています」という 1 回限りのプロンプトが表示された場合は、常に許可をクリックします。

後でエントリを削除するには: apple-mail-mcp setup-imap --account iCloud --uninstall

環境変数によるフォールバック（uvx / ヘッドレス / CI）

Keychain が使用できないコンテキストがあります: uvx 実行（一時的なバイナリパスが Keychain の ACL を壊し、再プロンプトや失敗を引き起こす）、Docker / CI（Keychain がまったくない）、バックグラウンドサービス（ACL プロンプトが UI なしで永久にブロックされる）。そのような場合、代わりに環境変数で IMAP パスワードを提供できます:

APPLE_MAIL_MCP_IMAP_PASSWORD_<SUFFIX>

<SUFFIX> は Mail.app のアカウント名を大文字にしたもので、非英数字の連続は単一のアンダースコアにまとめられ、先頭と末尾のアンダースコアは削除されます:

空でない値が設定されている場合、そのアカウントの Keychain エントリよりも環境変数が優先して使用されます（最初にチェックされ、security のシェルアウトはありません）。空または空白のみの値は無視され、Keychain のパスが使用されます。この検索は名前↔UUID フォールバックと組み合わされるため、呼び出し側がアカウントの UUID を渡した場合でも、アカウント名をキーにした環境変数が見つかります。

⚠️ セキュリティ上のトレードオフ。 環境変数は Keychain よりもはるかにプライバシーが低いです — ps -E、launchctl getenv、/proc スタイルのイントロスペクション、プロセスクラッシュダンプで表示可能で、ログやシェル履歴に漏れやすいです。Keychain が本当に選択肢にない場合のみ使用してください（uvx、Docker、CI、ヘッドレス）。Claude Desktop や標準のローカルインストールでは、setup-imap + Keychain を使用してください。

注意: 名前→サフィックスのマッピングは可逆ではありません — Yahoo! と Yahoo はどちらも YAHOO にマップされ、ASCII の英数字を含まないアカウント名には環境変数形式がありません（そのような場合は Keychain を使用してください）。

セットアップの検証。 setup-imap コマンドがこれを実行します。事後的に確認したい場合:

uv run python -c "from apple_mail_mcp.mail_connector import AppleMailConnector; \
    print(AppleMailConnector().search_messages(account='<ACCOUNT_NAME>', limit=1))"

IMAP が機能している場合、呼び出しは約 1 秒で返ります。フォールバックに関する WARNING がログに記録される場合（--log-level=DEBUG で表示可能）、アカウント名が Mail.app のアカウント名と完全に一致していること、Keychain エントリのメールアドレスが email addresses of account が返すものと一致していることを確認してください。

既知のプロバイダー固有の癖。

• iCloud: IMAP サーバーは LOGIN ユーザー名として @icloud.com / @me.com エイリアスを受け付けますが、Apple ID のメールアドレスは受け付けません。そのため、サーバー（および setup-imap）は Mail.app から email addresses of account を読み取ります。iCloud の Apple ID がサードパーティのアドレス（例: @gmail.com の Apple ID）で、かつ Mail.app がそのアカウントに @icloud.com アドレスを報告しない場合、自動検出では正しいログインを見つけられません — setup-imap は --email <あなたの @icloud.com/@me.com アドレス> を付けて再実行するようヒントを出して失敗します。その --email の値は永続化され（~/.apple_mail_mcp/imap_login_overrides.json）、ランタイムの解決でも同じログインが使用されます（#341）。これは一般的なオーバーライドです — 自動検出された IMAP ログインが正しくないアカウントに使用してください。

• Yahoo: アプリパスワードは段階的に廃止されています。すべてのアカウントでオプションが利用できるとは限りません。Yahoo のアカウントセキュリティページにオプションが表示されない場合、そのアカウントでは IMAP セットアップは不可能で、AppleScript のみが利用可能です。

• Gmail: 2 段階認証が有効である必要があります。Google Workspace 管理者がテナントレベルでアプリパスワードを無効にしている場合、そのアカウントでは IMAP セットアップは不可能です。

• Gmail のスレッド取得 — All Mail 表示のトレードオフ。 find_thread_members（スレッド対応クエリで内部的に使用）は、[Gmail]/All Mail が IMAP で公開されている場合に最速です — そのパスは約 5 往復で、メールボックス数に依存しません。多くのユーザーは All Mail を非表示にしています（Gmail 設定 → 転送と POP/IMAP → フォルダサイズの制限 → 「IMAP に表示しない」）。これはすべてのメールが重複するためです。非表示の場合、コネクタはメールボックスごとの X-GM-THRID 反復にフォールバックします（それでも汎用 BFS より約 6 倍高速ですが、ラベル数に比例します — 92 ラベルのアカウントで約 25 秒）。最高速度を求めるなら All Mail を公開し、IMAP フォルダリストをすっきりさせたいなら非表示のままにしてください。

書き込み操作（create_draft、update_draft、send_now=true の送信パスを含む）は、IMAP 設定に関係なく常に AppleScript を使用します — これらは Mail.app の作成 UI が必要です。

非常に大規模なメールボックスでのタイムアウト

デフォルト値は通常のメールボックス向けに設定されており、大規模なメールボックスでは引き上げる価値があります。このモジュール自身の測定では、47k 件のメールボックスでコールドキャッシュ 100 件のメールに 148 秒かかるため、サーバーサイドの SEARCH が 30 秒のデフォルトを超えて、より遅い AppleScript パスに静かにフォールバックする可能性があります。

数値でない値や非正の値は警告とともに無視され、デフォルトが維持されるため、タイプミスでサーバーがダウンすることはありません。

開発

# Setup
uv sync --dev

# Common commands
make test              # Run unit tests
make lint              # Lint with ruff
make typecheck         # Type check with mypy
make check-all         # All checks (lint, typecheck, test, complexity, version-sync, parity)
make coverage          # Coverage report
make test-integration  # Integration tests (requires Mail.app)

# Validation scripts
./scripts/check_version_sync.sh          # Version consistency
./scripts/check_client_server_parity.sh  # Connector-server alignment
./scripts/check_complexity.sh            # Cyclomatic complexity
./scripts/check_applescript_safety.sh    # AppleScript safety audit

ブランチ規約

{type}/issue-{num}-{description} — 例: feature/issue-42-thread-support

アーキテクチャ

server.py (FastMCP tools — thin orchestration, validation, elicitation gates)
  -> mail_connector.py (dispatch + domain logic)
     -> AppleScript path:  subprocess.run(["osascript", ...]) -> Apple Mail.app   (universal baseline)
     -> IMAP fast path:    imap_connector.py -> the account's IMAP server          (when hinted + Keychain creds)

ディスパッチモデル。 AppleScript は常に利用可能なベースラインです。読み取り/変更呼び出しが account（および、該当する場合は mailbox）ヒントを提供し、かつアカウントが Keychain IMAP 資格情報を持っている場合、 コネクタはサーバーサイドの IMAP 高速パスを取ります。IMAP で失敗した場合は AppleScript にフォールバックするため、 機能が失われることはありません。速度が向上するだけです。 完全なディスパッチモデル、デュアルエミットの message-ID スキーム、下書きのライフサイクル、および IMAP スレッド層については、 docs/reference/ARCHITECTURE.md を参照してください。

• server.py — MCP ツール登録、入力検証、確認（エリシテーション）ゲート、レスポンス整形

• mail_connector.py — AppleScript の生成/実行 + IMAP 高速パスディスパッチ

• imap_connector.py — IMAP クライアント + 接続プール（検索、フェッチ、一括変更の高速パス）

• security.py — 入力サニタイズ、監査ログ、確認フロー

• utils.py — 純粋関数: エスケープ、パース、検証

• exceptions.py — 型付き例外階層

セキュリティ

• ローカル実行のみ（クラウド処理なし）

• 既存の Mail.app 認証を使用。IMAP アプリパスワード（オプトイン）は macOS Keychain に保存され、リポジトリや設定には決して保存されません

• すべての入力はサニタイズされ、AppleScript エスケープされます（AppleScript インジェクション対策）

• 破壊的操作は MCP エリシテーションによるユーザー確認が必要。さらにレート制限と監査ログ

• save_attachments はディスク充填 DoS に対してバイト上限（添付ごと + 合計）が設定されています

ドキュメント:

• SECURITY.md — 脆弱性報告ポリシー

• docs/SECURITY.md — ユーザー向けのセキュリティ体制とプライバシー

• docs/guides/THREAT_MODEL.md — STRIDE 信頼境界分析

• docs/guides/SECURITY_CHECKLIST.md — 機能ごとのコントリビューター向けチェックリスト

コントリビューティング

開発ワークフロー、コーディング標準、PR プロセスについては、CONTRIBUTING.md を参照してください。

クレジット

このプロジェクトは、Morgan Jeffries による apple-mail-mcp のフォークです。この元プロジェクトがすべての重労働を担っています。AppleScript ブリッジ、IMAP 高速パス、下書き状態ストア、テンプレート、エリシテーションゲートです。

このフォークがアップストリーム v0.10.2 に追加するもの:

ツールサーフェス、テスト、ドキュメントを含むその他すべてはアップストリーム由来です。共有部分のバグ報告は、そちらに提出するのがよいでしょう。

Mail.app がこのサーバーに許可しないこと

macOS 15 で確認済み。issue を開く前に知っておく価値があります:

• AppleScript 経由で作成されたアカウントは永続化されません。 make new imap account は id を返し、count of accounts はそれを認識しますが、Mail の設定ウィンドウには表示されず、 Mail を終了すると消えます。実際にアカウントを追加するには、画面上で承認された構成プロファイル （com.apple.mail.managed）が必要です。スクリプトによる方法はありません。 profiles install は「profiles tool no longer supports installs」と応答します。

• enabled はどのアカウントにも書き込めません。 set enabled は、 -10000 AppleEvent handler failed を、新しいアカウントでも既存のアクティブなアカウントでも、 AppleScript と JXA の両方で、あらゆる参照形式で発生させます。Mail 自身の sdef はプロパティを書き込み可能と宣言しています （access="r" なし、cocoa キー isActive）が、実装はそれに同意しません。

• Mail の設定ウィンドウは古いスナップショットです。 AppleScript がもはや認識しないアカウントを一覧表示し、 認識しているアカウントを省略します。UI からアカウント状態を読み取ってはいけません。

ライセンス

MIT