Apple Mail MCP Server

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

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

ツール (23)

コア: list_mailboxes, search_messages, get_messages, update_message 下書きライフサイクル: create_draft, update_draft, delete_draft メールボックス CRUD: create_mailbox, update_mailbox, delete_mailbox 添付ファイルと管理: save_attachments, delete_messages 検出とルール: list_accounts, list_rules, get_thread, create_rule, update_rule, delete_rule テンプレート: list_templates, get_template, save_template, delete_template, render_template

完全なパラメータと戻り値の形状のドキュメントは docs/reference/TOOLS.md を参照してください。

Related MCP server: apple-mail-mcp

前提条件

• macOS 10.15 (Catalina) 以降

• Python 3.10 以降

• Apple Mail が少なくとも1つのアカウントで設定されていること

• uv（推奨）または pip

インストール

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

設定

Claude Desktop の設定ファイル (~/Library/Application Support/Claude/claude_desktop_config.json) に追加してください:

{
  "mcpServers": {
    "apple-mail": {
      "command": "uv",
      "args": ["--directory", "/path/to/apple-mail-mcp", "run", "python", "-m", "apple_mail_mcp.server"]
    }
  }
}

権限

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

任意: IMAP を使用した高速な検索

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

仕組み。 キーチェーンにエントリが存在する場合、サーバーは IMAP（高速でサーバーサイドの SEARCH）を使用します。それ以外の場合、または IMAP が失敗した場合（オフライン、パスワード間違い、タイムアウト）、静かに AppleScript にフォールバックします。機能を失うことはなく、IMAP が設定され到達可能な場合にのみ速度が向上します。設定フラグや環境変数はありません。Keychain エントリの存在がオプトインです。

アカウントごとに一度だけ必要な初期設定。

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

   • iCloud: appleid.apple.com/account/manage → App-Specific Passwords（アプリ固有のパスワード）。Apple ID で 2FA（2要素認証）が必要です（既定）。

   • 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 で上書き可能）

   • getpass で入力を求めるため、パスワードがシェル履歴に残りません

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

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

3. 次の IMAP ベースの呼び出しで「セキュリティが 'login' キーチェーンを使用します」というプロンプトが一度だけ表示された場合は、常に許可 をクリックしてください。

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

セットアップの確認。 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秒で完了します。フォールバックでの警告がログに記録された場合（--log-level=DEBUG で確認可能）、アカウント名が Mail.app のアカウント名と正確に一致し、Keychain エントリのメールアドレスが email addresses of account で返される内容と一致しているか確認してください。

既知のプロバイダー固有の注意点。

• iCloud: メールサーバーは IMAP のログイン・ユーザー名として Apple ID のメールではなく @icloud.com / @me.com エイリアスを使用します。そのため、サーバー（および setup-imap）は Mail.app から email addresses of account を読み取ります。

• 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 が必要です。

開発

# 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)
  -> mail_connector.py (AppleScript bridge — domain logic)
     -> subprocess.run(["osascript", ...])
        -> Apple Mail.app

• server.py — MCP ツールの登録、入力検証、レスポンスの整形

• mail_connector.py — すべての AppleScript の生成と実行

• security.py — 入力のサニタイゼーション、監査ログ、確認フロー

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

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

セキュリティ

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

• 既存の Mail.app 認証を使用（資格情報の保存なし）

• すべての入力をサニタイズし、AppleScript 開いて

• 破壊的操作には確認が必要

• 操作監査ログ

• ポリシーは SECURITY.md、詳細な分析は docs/Security.md を参照してください

コントリビューション

開発ワークフロー、コーディング規約、PR（プルリクエスト）プロセスについては CONTRIBUTING.md を参照してください。

ライセンス

MIT