Apple Mail MCP

apple-mail-mcp

Claude（または任意の LLM）に Apple Mail と iCloud へのアクセスを許可する唯一の方法です。

Gmail と Outlook には API がありますが、iCloud にはありません。Apple Mail にメールが保存されている Mac ユーザーの場合（iCloud、iCloud+、または Apple Mail 経由で同期されているアカウント）、LLM が呼び出せる Web API はありません。このサーバーは、ローカルマシン上の AppleScript を使ってそのギャップを埋めます。

Claude に Apple Mail の完全な操作権限を与えます。クラウドの仲介を挟まず、実際の受信トレイを対象に、自然言語を使ってメッセージの読み取り、検索、作成、返信、移動、フラグ設定、削除を行えます。

osascript 経由で AppleScript を使用して構築されており、リアルタイムの新着メールイベントに対応する MailKit 拡張機能をオプションで利用できます。

---

ツール

ツール	説明
list_folders	すべてのアカウントとそのメールボックスを一覧表示します
create_folder	アカウントに新しいメールボックス／フォルダーを作成します（冪等）
list_emails	メールボックス内のメッセージをページ分割して表示します（新しい順）
get_email	メッセージのすべてのヘッダーと本文を読み取ります
search_emails	メールボックスを横断して、送信者、件名、日付範囲で絞り込みます
compose_email	下書きを作成するか、新しいメッセージをすぐに送信します
reply_email	メッセージに返信し、下書きとして開くか、すぐに送信します
move_email	メッセージを任意のメールボックスに移動します
move_matching	フィルターに一致するすべてのメッセージをメールボックスに一括移動します
archive_email	アーカイブ（iCloud）またはすべてのメール（Gmail）に移動します
move_to_junk	迷惑メール（iCloud）またはスパム（Gmail）に移動します
flag_email	メッセージのフラグを設定または解除します
mark_read	メッセージを既読または未読にします
delete_email	削除済みメッセージ（iCloud）またはゴミ箱（Gmail）に移動します
create_rule	送信者のドメインに基づいてフォルダーに振り分ける、標準の Mail ルールを作成します（既存のメールも並べ替えるかどうかを選択できます）
list_rules	移動先フォルダーと一致する送信者ドメインを含め、すべての Mail ルールを一覧表示します
delete_rule	名前を指定して Mail ルールを削除します
get_pending_events	MailKit ブリッジからリアルタイムの新着メールイベントを取得します
summarize_email	ローカル AI を使ってメッセージを2～3文で要約します
classify_email	ローカル AI を使ってカテゴリ、優先度、対応の要否で分類します
draft_reply	ローカル AI を使って返信本文の下書きを作成します（送信前に確認してください）
triage_inbox	最大20件のメッセージを優先度順に一括分類します

---

必要条件

• macOS（Sonoma／Sequoia／macOS 26 でテスト済み）
• Apple Mail が起動しており、少なくとも1つのアカウントが設定されていること
• Node.js 18+
• LM Studio（任意）— ローカル AI ツール用です。OpenAI 互換のサーバーであればどれでも動作します

---

インストール

npx（推奨）

~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "apple-mail": {
      "command": "npx",
      "args": ["-y", "@jdot6/apple-mail-mcp"]
    }
  }
}

Claude Desktop を再起動し、「メールにフォルダーはいくつありますか？」と尋ねてみてください。

ブートストラップスクリプト

リポジトリをクローンしてビルドし、Claude の設定を自動的に更新します：

curl -fsSL https://raw.githubusercontent.com/jayvee6/apple-mail-mcp/master/install.sh | bash

手動

git clone https://github.com/jayvee6/apple-mail-mcp.git
cd apple-mail-mcp
npm install && npm run build

~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "apple-mail": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/apple-mail-mcp/dist/index.js"]
    }
  }
}

which node を実行して、Node バイナリの完全なパスを取得します。Claude Desktop を再起動してください。

オートメーションのアクセス許可

メールツールを初めて使用するとき、macOS から node に Mail の制御を許可するか確認されます。許可をクリックしてください。誤って拒否した場合は、システム設定 → プライバシーとセキュリティ → オートメーションに移動し、使用するターミナルまたは Node.js ランタイムに対して再度有効にしてください。

---

ローカル AI（任意）

AI ツールは、LM Studio または OpenAI 互換サーバーを介して、任意のローカル LLM で実行できます。デフォルト設定では、メールデータがマシンの外に送信されることはありません。

claude_desktop_config.json の環境変数で設定します。

{
  "mcpServers": {
    "apple-mail": {
      "command": "npx",
      "args": ["-y", "@jdot6/apple-mail-mcp"],
      "env": {
        "APPLE_MAIL_AI_PROVIDER": "lmstudio",
        "APPLE_MAIL_AI_ENDPOINT": "http://localhost:1234",
        "APPLE_MAIL_AI_MODEL": "gemma-4-it"
      }
    }
  }
}

変数	デフォルト	説明
APPLE_MAIL_AI_PROVIDER	lmstudio	lmstudio | openai | foundation | none
APPLE_MAIL_AI_ENDPOINT	http://localhost:1234	AI サーバーのベース URL
APPLE_MAIL_AI_MODEL	gemma-4-it	モデル識別子
APPLE_MAIL_AI_API_KEY	(none)	リモートプロバイダー用のベアラートークン
APPLE_MAIL_AI_ENRICH_EVENTS	(off)	新しいメールイベントを自動分類するには 1 を設定します
APPLE_MAIL_AI_ALLOW_REMOTE	(off)	localhost 以外の AI エンドポイントを許可するには 1 を設定します

プライバシーに関する注意： APPLE_MAIL_AI_ENDPOINT にリモートサーバー（例：OpenAI）を指定すると、メールの全文がそのサーバーに送信されます。サーバーはデフォルトでこれをブロックします。これを承知のうえで有効にするには、APPLE_MAIL_AI_ALLOW_REMOTE=1 を設定する必要があります。

---

付属スキル — メール作成レビュー

このリポジトリの skill/SKILL.md ファイルは Claude スキルです。Claude が作成するすべてのメールに、マルチエージェントレビューのパイプラインを追加します。作成ウィンドウを開く前に、Claude は下書きを5つの並列レビュアーにかけます。

レビュアー	チェック項目
文章の粗さ検出	AI らしい文章の特徴、冗長な表現、企業の流行語
コピーエディター	スペル、文法、句読点
能動態	受動態から能動態への書き換え
正確性	名前、日付、事実が文脈と一致しているか
論理と明瞭さ	依頼内容の明確さ、論理的な構成、適切な長さ

調停役がレビューを統合し、修正済みの下書きと変更履歴を作成します。Claude は結果を表示し、Mail で下書きを開く前にあなたの承認を待ちます。LLM が作成したメールに send: true が使われることはありません。送信は自分で Mail から行います。

Claude Code にスキルをインストールするには：

/skill install /path/to/apple-mail-mcp/skill/SKILL.md

---

仕組み

Claude ──stdio──▶ MCP server (Node.js)
                      │
                      ├── runScript("list_messages", [...args])
                      │        │
                      │        └── osascript scripts/applescript/list_messages.applescript
                      │                 │
                      │                 └── Apple Mail (AppleScript dictionary)
                      │
                      └── HTTP bridge  ◀── MailKit extension (optional)
                          localhost:27182

メッセージ参照は、壊れやすい整数インデックスを使わずにメッセージを一意に識別する複合キーです。

{account}::{mailbox}::{RFC 2822 Message-ID}

e.g.  iCloud::INBOX::<[email protected]>

各リスト／検索結果には message_ref が含まれます。個々のメッセージを操作するツール（get_email、reply_email、move_email など）は、この参照を入力として受け取ります。アカウントとメールボックスの各要素によって AppleScript の検索対象が適切なメールボックスに限定され、RFC 2822 ID が安定した識別子になります。Mail の whose 述語により、メッセージごとの検索は O(1) で実行されます。

---

MailKit Bridge（任意）

MailKitBridge/ ディレクトリには、メッセージの受信時に localhost:27182/event へローカル HTTP POST を送信する Mail 拡張機能の Xcode プロジェクトが含まれています。これにより、手動でポーリングしなくても get_pending_events にリアルタイムでデータが反映されます。

MCP サーバーは起動時に HTTP リスナーを開始します。拡張機能がインストールされていない場合は何もしません。

拡張機能をビルドしてインストールするには、Xcode で MailKitBridge/MailKitBridge.xcodeproj を開き、MailKitBridgeApp スキームをビルドします。アプリを一度実行して拡張機能を登録し、Mail → 設定 → 拡張機能で有効にします。

---

開発

npm run dev          # run with tsx (no build step)
npm run build        # compile TypeScript → dist/
npm run typecheck    # type-check without emitting

AppleScript ファイルは scripts/applescript/ にあり、osascript から直接呼び出されます。コンパイルは不要です。単独でテストできます。

osascript scripts/applescript/list_folders.applescript
osascript scripts/applescript/list_messages.applescript "iCloud" "INBOX" "1" "5"

---

セキュリティに関する注意事項

• HTTP ブリッジは 127.0.0.1 のみにバインドされており、マシンの外部からはアクセスできません。
• パストラバーサルを防ぐため、スクリプト名は使用前に path.basename() で検証されます。
• 引数はシェルを介さず、execFile を使って osascript に渡されるため、シェルインジェクションの攻撃経路はありません。
• Mail がフリーズした場合や、権限を求めるプロンプトを表示している場合に処理が停止するのを防ぐため、AppleScript 呼び出しは 30 秒後にタイムアウトします。
• メッセージ本文に含まれるプロンプトインジェクション攻撃を防ぐため、AI プロンプト内のメール内容は XML の区切り文字（<email>…</email>）で囲まれます。
• リモート AI エンドポイントはデフォルトでブロックされています。メールデータをデバイス外に送信する場合は、明示的にオプトインするため APPLE_MAIL_AI_ALLOW_REMOTE=1 を設定してください。

---

ライセンス

MIT