apple-mail-mcp

uvx apple-mailbox-mcp setup

✨ できること

🔍 メールボックスに質問する。 「先週 Maria がメモについて送ってきたものは?」 検索はデータベースの速度で実行され — 送信者、メールボックス、日付、未読、添付ファイル — 会話全体を再構築します。

🕳️ Mail 自身では見つけられないものを見つける。 Mail の組み込み検索は、ほとんどのメッセージの最初の 1 行しかざっと見ません。apple-mail-mcp は Mac 上のすべてのメッセージ本文をインデックス化します — さらに Exchange アカウントでは、Mail がダウンロードしなかった本文さえ、サーバー上のあなた自身のメールボックスから直接取得します。何も返さなかったクエリが 20 件を返すようになります。

🎭 適切な「あなた」として送信する。 仕事のメールは仕事のレーンで、個人のメールは Gmail で — 1 つのパラメータが Identity を選びます。すべてのメッセージはゼロから、クリーンで標準に準拠したメールとして作成され、どこでも正しく表示されます、Outlook を含めて (Outlook で空白で届く AppleScript の作成パスこそ、このプロジェクトが存在する理由です)。

⏰ 「Send Later」のようにスケジュール、ただしスクリプト化可能。 予約メッセージは完全に凍結されます — 添付ファイル、Identity、正確なテキスト、そして 1.8.2 以降はスレッディングヘッダーも。そのため予約された返信は、それが返信する会話に届きます。Exchange は蓋を閉じたまま、指定された時刻にサーバー側で実行できます。他のプロバイダーはローカルのバックグラウンド送信機能を使い、次のパスで配信します (または Mac のスリープ解除直後)。

🗂️ 大規模なトリアージを、恐れずに。 「この 40 件のニュースレターを整理して」 はレビュー可能なプランになります。承認されるまで何も移動せず、触れる前にすべてのメッセージが再確認され、その後結果が Mail 自身の記録と照合されます。削除は Mail のゴミ箱を意味します — 何も完全に消去されることはありません。

📝 下書きは下書きのある場所で。 実際の Exchange の下書きフォルダに作成し、Outlook や OWA ですぐに開けます — 作成されるだけで、自動送信は決してされません。

⚡ 他とは違う理由

他のすべての Apple Mail 向け MCP は、検索と操作の両方で AppleScript を動かします。 これは違います — そしてその違いは明らかです:

上記の数値はすべて、稼働中の約 30 万件のメッセージストアで実測したものです。 スクリプトと完全な手法は docs/benchmarks.md にあります。

これらのベンチマークがあなたのメールボックスでも成り立つなら、⭐ が他の人の発見につながります。

🛡️ 信頼されるために作られています

• ✅ プラン → レビュー → 適用 → 検証。 一括操作は、何かが起こる前に読めるプランとして凍結されます。結果はその後、Mail 自身のストアと照合して確認され、決して推測されません。
• 🗑️ 何も削除されることはありません。 「削除」は Mail のゴミ箱にファイルするだけで、破壊的なプランには独自の、上限付きの別の入口があります。
• 👓 読み取り専用メールモード。 EMAIL_MCP_READ_ONLY=1 を設定すると、セッションには変更を加えない 11 個のメールツールだけが存在します。検索はローカルの本文インデックスを維持することがあり、添付ファイルの取得は要求されたファイルを設定済みの一時ディレクトリに書き込みます。
• 💾 クラッシュに強い予約送信キュー。 マニフェストの更新はフラッシュされ、アトミックに置き換えられるため、中断された書き換えでも最後の有効なレコードが保持されます。ファイルが単独で破損した場合、診断はキューが空だと主張するのではなく、そのファイルを名指しし、正常な予約メッセージは動き続けます。
• 🧾 ローカルのベストエフォート型アクティビティ台帳。 送信、予約、キャンセル、トリアージ実行は記録されますが、書き込み不能なログがメールをブロックすることはありません。照合には、メッセージ自体、その Message-ID、およびその予約レコードが引き続き正式な情報源となります。
• 🔒 サードパーティのメールリレーはありません。 メール内容は、あなたが送信するメール、および Exchange/IMAP の本文バックフィル、下書き、サーバー側スケジューリングのための自身のプロバイダーへの任意アクセスを除いて、ローカルに留まります。SMTP パスワードは macOS Keychain または 1Password に保持され、Microsoft OAuth トークンは ~/.email-mcp/graph/ 配下のプライベートな 0600 キャッシュに保存されます。
• 📜 書面による契約。 v1.0 以降、すべてのツールの形状、エラーコード、上限は追加的に進化し、800 件以上の自動テストによって維持されています。
• 🤝 すべての MCP クライアントにとって明確。 21 個のツールすべてが、何をするかを示し、すべての入力を説明し、データを読み取るのか、変更するのか、削除できるのかを宣言します。新しいクライアントは構造化された結果を受け取り、古いクライアントは同じ JSON テキストを受け取ります。MCP SDK 2.2 およびそれ以降の 2.x リリースがテストされており、古いクライアントもサポートされています。
• 🧱 あなたのワークフローを壊さずに進化するように作られています。 メールルールは MCP、Mail.app、Exchange、配信、ローカルストレージから分離されています。プロバイダーや SDK の変更はエッジに留まり、21 ツールの契約は安定したままです。依存関係のルールは CI で強制され、アーキテクチャガイドで説明されています。
• 📦 検証できるリリース。 タグ付けされたすべてのリリースは、公開前にクリーンな環境でビルドおよびインストールされます。GitHub にはソースコードだけでなく、wheel、ソースアーカイブ、SHA-256 チェックサム、署名済みビルド来歴が含まれます。
• 🩺 自己診断。 apple-mail-mcp status は、読みやすくまとまった 1 つの準備状況・スケジューリング・リカバリー画面を提供します。apple-mail-mcp doctor は完全な診断詳細と、赤い項目に対する正確な修正方法を提供します。

🚀 クイックスタート

1. ターミナルアプリに フルディスクアクセス を許可します （システム設定 → プライバシーとセキュリティ → フルディスクアクセス）。その後、ターミナルを終了して再度開きます。これはAppleによる手動設定が必要な唯一の項目です。ポップアップは表示されません。

2. インストールしてセットアップします：

   uvx apple-mailbox-mcp setup     # or: pipx install apple-mailbox-mcp
   # or via Homebrew:
   brew install parasxos/tap/apple-mail-mcp && apple-mail-mcp setup
   

3. クライアントに登録します — Claude Codeの場合は次の1行を実行します：

   claude mcp add --transport stdio --scope user apple-mail -- uvx apple-mailbox-mcp
   

   または、Claude Desktop／Cursor／VS Codeの場合は、同じJSONブロックを設定します （claude_desktop_config.json / .cursor/mcp.json / .vscode/mcp.json）：

   {
     "mcpServers": {
       "apple-mail": { "command": "uvx", "args": ["apple-mailbox-mcp"] }
     }
   }
   

4. 確認します： uvx apple-mailbox-mcp status を実行すると、準備状況が1画面に表示されます。または、クライアントに doctor ツールを実行するよう頼んでください。赤い項目には、それぞれ具体的な修正方法が表示されます。uvx apple-mailbox-mcp --version を実行すると、インストール済みのバージョンが表示されます（apple-mailbox-mcp、apple-mail-mcp、email-mcp は同じコマンドの3つの名前です）。大きなメールボックスでは、初回の本文インデックス作成はバックグラウンドで実行され、数分かかることがあります。検索はすぐに使え、インデックスの作成に伴って処理が完了します。

setup を実行する前に、ターミナルアプリに フルディスクアクセス を許可してください （システム設定 → プライバシーとセキュリティ → フルディスクアクセス）。これにより、読み取りを高速かつローカルで行えます。この設定にはポップアップが表示されません。Appleによる手動設定が必要な唯一の項目で、見つからない場合は setup が該当する設定画面まで案内します。

setup では、すべての項目がわかりやすい言葉で尋ねられます（何も入力せずにEnterキーを押すと、推奨される回答が選択されます）。送信者のIDを選択でき、本文検索用インデックスが作成され、夜間の更新が実際に実行されることが確認されます。最後に、MCPクライアントに貼り付けるブロックが1つ表示されます：

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

セットアップの最後に、明確な 準備完了 の判定、または番号付きの復旧手順が表示されます。トリアージで初めて求められたときに、オートメーション → Mail を許可してください。インストール状況、次に予定されているメッセージ、失敗した予定送信は、いつでも apple-mail-mcp status で確認できます。詳しい技術情報を確認するには、apple-mail-mcp doctor を使用してください。

💡 ターミナルを使い始めたばかりですか？ 間違っているように見えても、問題のないことが3つあります： brew install pipx では y の入力が必要です（Enterキーだけでは受け付けられません）。 pipx ensurepath で ⚠️ が表示されることがありますが、その後に表示される「pipx is ready to go!」の行が判定結果です。また、ensurepath の実行後は、apple-mail-mcp が見つかるように、ターミナルを一度閉じて再度開いてください。

🔌 対応クライアント

以下のクライアントはすべてstdio MCPに対応しています。コマンドは常に uvx apple-mailbox-mcp です。

Claude Code

claude mcp add --transport stdio --scope user apple-mail -- uvx apple-mailbox-mcp

Claude Desktop

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

{ "mcpServers": { "apple-mail": { "command": "uvx", "args": ["apple-mailbox-mcp"] } } }

Cursor

同じブロックを ~/.cursor/mcp.json（またはプロジェクトごとの .cursor/mcp.json）に追加します。

VS Code（Copilot MCP）

.vscode/mcp.json の "servers" の下に同じブロックを追加します。

Codex CLI

# ~/.codex/config.toml
[mcp_servers.apple-mail]
command = "uvx"
args = ["apple-mailbox-mcp"]

任意のstdio MCPクライアント

uvx apple-mailbox-mcp を指定します。ワイヤーコントラクトはv1.0以降、追加のみです。

🔧 トラブルシューティング

🧰 21 個のツール

添付ファイルは双方向に対応し、サイズの上限が設けられています。返信はあらゆる クライアントで正しくスレッド化されます。スケジュール送信はスリープを乗り越えます — 蓋が閉じている間に送信予定だったメッセージは、スリープ解除後の最初のティックで送信されるか、 Exchange 経由なら正確に予定どおりに送信されます。

🎭 あなたのアドレス、あなたのレーン

From: アドレスがメールの送信方法を決定します。~/.email-mcp/identities.toml:

default = "work"

[work]                    # sent through a host you already trust, over SSH
from_addr = "[email protected]"
driver    = "ssh_sendmail"
host      = "bastion.example.org"   # any login host you already SSH to

[gmail]                   # classic SMTP — the app password stays in 1Password
from_addr = "[email protected]"
driver    = "smtp"
host      = "smtp.gmail.com"
op        = "op://Personal/gmail app password/password"

Exchange の ID では、サインインを 1 つ追加すると拡張機能を利用できます。 実際の Drafts フォルダに下書きが保存され、スケジュール送信はサーバー自身によって 実行されます — 蓋を閉じたまま、Mac がスリープしていても。setup ではこれを 1 つの簡単な質問で提案します。読み取りには送信設定は一切必要ありません。