Apple Mail

Apple Mail MCP

macOS の Apple Mail 用 MCP サーバーです。

メールボックス、メッセージの検索と閲覧、メールの作成にアクセスできます。Mail を信頼できる唯一の情報源として維持しながら、エージェントがメールを検索、閲覧、下書き、送信できるようにします。

使用する場面

• Mail のみを使用するワークフロー
• オールインワンサーバーよりも厳格な権限が必要な場合
• ネイティブの Mail アプリを介した下書きと送信のワークフロー

機能

• メールボックスの一覧表示
• メッセージの検索と閲覧
• 下書きの作成とメッセージの送信
• 返信、転送、既読／未読の切り替え、移動、削除
• コンテキストに制約のあるクライアント向けのツール検出ヘルパー search_tools と get_tool_info
• スレッド用ヘルパー：mail_get_thread、mail_reply_latest_in_thread、mail_archive_thread
• メールボックスリソースと返信向けプロンプト
• ヘルスチェックと権限チェック：mail_health、mail_permission_guide、mail_recheck_permissions

ツール

mail_health、mail_permission_guide、mail_recheck_permissions、mail_list_mailboxes、mail_search_messages、mail_get_message、mail_get_thread、mail_compose_draft、mail_send_message、mail_reply_message、mail_forward_message、mail_mark_message、mail_move_message、mail_delete_message、mail_reply_latest_in_thread、mail_archive_thread、mail_list_prompts、mail_get_prompt、および検出ヘルパーの search_tools と get_tool_info。

この Mac にインストールする

uvx apple-mcp-mail

git clone https://github.com/JonathanRReed/Apple-MCPs.git
cd Apple-MCPs
uv sync --all-packages

AI エージェントにインストールする

{
  "mcpServers": {
    "apple-mail": {
      "command": "uvx",
      "args": ["apple-mcp-mail"],
      "env": {
        "APPLE_MAIL_MCP_SAFETY_PROFILE": "safe_manage",
        "APPLE_MAIL_MCP_VISIBLE_DRAFTS": "true"
      }
    }
  }
}

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

安全モード

APPLE_MAIL_MCP_SAFETY_PROFILE でモードを設定します。

• safe_readonly：閲覧と検索のみ
• safe_manage：閲覧、下書きの作成、返信、下書きとしての転送、既読／未読の切り替え、移動、削除、スレッドのアーカイブができます。新規メッセージの送信はブロックされます。返信は即時に送信されるため、このモードでもスレッド内の既存の相手にメールを送信する場合があります。転送は任意のアドレス宛てに送信できるため、ユーザーが確認できるよう、Mail に未送信の下書きとして保存されます。転送を直接送信するには full_access に切り替えてください
• full_access：新規メッセージの送信を含む、このリポジトリの Mail ツール一式を利用できます

削除やアーカイブを行うために、safe_manage から full_access に切り替える必要はありません。

サーバーのインストール方法によって、デフォルトは異なります。

Claude Desktop で変更するには、「設定」>「拡張機能」を開き、Apple Mail を選択して「構成」をクリックし、「Mail の安全モード」を設定します。他のクライアントでは、サーバーの env ブロックで APPLE_MAIL_MCP_SAFETY_PROFILE を設定し、クライアントを再起動してください。ツールがブロックされた場合、エラーに設定名と使用すべき値が表示されます。値が無効または空白の場合は safe_readonly が選択され、mail_health の safety_mode_warning に説明が表示されます。

APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT（バンドル設定：「Mail の添付ファイルフォルダー」）を専用フォルダーに設定するまで、添付ファイルは無効です。

トランスポート

デフォルトで推奨されるトランスポートは stdio です。代わりに Streamable HTTP を提供するには、APPLE_MAIL_MCP_TRANSPORT=streamable-http を設定します（必要に応じて APPLE_MAIL_MCP_HOST と APPLE_MAIL_MCP_PORT も設定できます）。

macOS の権限

• Mail へのオートメーションアクセスが必要です

移動／削除エラーのトラブルシューティング

Issue #23 では、item ... of every message/mailbox/account を含む AppleScript の -1728 エラーが報告されています。移動および削除のスクリプトは、アカウント／メールボックスの一致を具体的なオブジェクトに解決し、位置ベースの repeat ループ参照を保持する代わりに、元のメールボックス内で Mail の数値 ID を使ってメッセージを検索するようになりました。対象が見つからない場合や曖昧な場合は処理を拒否し、変更操作を自動で再試行することはありません。

mail_search_messages が返したとおりの message_id を使用してください。メッセージが移動済みであるか、元のメールボックスで ID を解決できなくなった場合は、ID を編集せず、もう一度検索してください。ACCOUNT_AMBIGUOUS、MAILBOX_AMBIGUOUS およびそれらに対応する TARGET_ 付きのエラーは、設定された名前では要求されたオブジェクトを一意に特定できないことを意味します。再試行する前に、選択対象を一意にしてください。権限エラーを含むその他のネイティブエラーは、そのまま表示されます。

アーカイブするには、mail_list_mailboxes を呼び出し、実際の移動先の名前を渡してください。特にローカライズされた Gmail ラベルや入れ子になった Gmail ラベルでは、アカウントに Archive という名前のメールボックスがあるとは限りません。アカウント間で移動する場合は、対象のアカウントを明示してください。

mail_health が正常に応答しても、移動／削除の往復処理が検証されたことにはなりません。新規インストールを検証するには、件名が一意な使い捨てメッセージを使い、検索して、要求した操作を 1 つ実行し、Mail で結果を確認してください。スレッドのアーカイブではメッセージが個別に移動され、トランザクションではありません。エラーの後にスレッド全体を再試行する前に、Mail を確認してください。

アップグレード後は MCP クライアントを再起動してください。GitHub にマージされた修正は、パッケージリリースに含まれるまで PyPI の uvx インストールでは利用できません。ソースをチェックアウトした場合は、上記のクローン手順でテストできます。統合サーバーには Apple-Tools-MCP/start.sh を使用してください。エラーが続く場合は、インストール済みのバージョンまたはソースのコミット、macOS のバージョン、操作、伏せ字にしたエラー文を報告してください。メッセージ本文や非公開のアカウント情報は投稿しないでください。

起動チェックリスト

• MCP クライアントに uvx apple-mcp-mail（またはクローンの AppleMail-MCP/start.sh）を追加します
• Mail のツールがコンテキストに読み込まれるよう、クライアントを再読み込みするか、再接続します
• サーバーに接続できることを確認するため、最初に mail_health を呼び出します
• Mail のオートメーションがブロックされている場合は、mail_permission_guide を呼び出します
• macOS の権限を変更した後は、mail_recheck_permissions を呼び出します

プロンプトに関する注意事項

• ユーザーがメールアドレスではなく人物を指定した場合は、送信または返信の前に Contacts を実行してください。
• tools/list は Mail のツール一覧をすべて返します。コンテキストに制約のあるクライアントは、まず search_tools を呼び出し、次に呼び出す予定の Mail ツールについて get_tool_info を呼び出せます。
• mail_search_messages にはクエリ文字列が必要です。送信者、件名の一部、またはワイルドカードとして * を使用してください。
• 特定のアカウントを検索するには、mail_list_mailboxes で取得したアカウント名を account に渡してください。指定しない場合、アカウントは Mail の順序で検索され、limit 件の結果が集まった時点で検索が終了します。そのため、最初のアカウントのメールが多いと結果がすべて埋まり、ほかのアカウントにある同名のメールボックスが見つからないことがあります。
• 最近のメールをすべて一覧表示するエンドポイントはありません。
• ユーザーが1件のメッセージではなく会話を指している場合は、mail_get_thread を使用してください。
• 会話の最新メッセージにエージェントが返信する場合は、mail_reply_latest_in_thread を使用してください。
• ユーザーがスレッド単位で整理することを望み、移動先が「アーカイブ」である場合は、mail_archive_thread を使用してください。
• ユーザーがテキストメッセージとメールのどちらを指しているか不明な場合は、「Messages」と「Mail」のどちらを使うか、選択する前に一度確認してください。
• Mail から特定の送信者として送信する必要がある場合は、正確な送信者のメールアドレスを from_account に渡してください。
• from_account は Mail 独自の sender プロパティ（Full Name <address>。名前にカンマまたは引用符が含まれる場合は、名前を引用符で囲みます）を通じて適用され、追加の macOS 権限は必要ありません。Mail がこれを受け付けない場合に限り、サーバーは System Events を使って「差出人」ポップアップから選択します。この場合は、System Events のオートメーション許可と、サーバーを実行するプロセスのアクセシビリティ許可も必要です。
• AppleScript の各呼び出しには、APPLE_MAIL_MCP_SCRIPT_TIMEOUT_SECONDS によるタイムアウトが設定されています（秒単位の整数で、既定値は 120、最小値は 5。無効な値や最小値未満の値には既定値が使用されます）。保留中の macOS 許可ダイアログは、リクエストが停止したままになるのではなく、エラーとして表示されます。既定値は、遅いものの正当な検索にも対応できるよう設定されています。4,900 件のメッセージがある Exchange メールボックスで、件名または送信者を検索した場合、約 56 秒かかりました。
• mail_send_message、mail_reply_message、mail_reply_latest_in_thread、または送信を伴う mail_forward_message がタイムアウトした場合、失敗ではなく SEND_STATUS_UNKNOWN が返されます。Mail がすでに送信している可能性があります。再試行する前に、アカウントの送信済みメールボックス（mailbox に Sent Messages、または mail_list_mailboxes に表示される Sent Items などの名前を指定して mail_search_messages を実行）を確認してください。確認せずに再試行すると、メッセージが二重に送信される可能性があります。

関連項目

• Apple-Tools-MCP

添付ファイルへのアクセス

APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT を、~/Documents/Mail Attachments のように任意のディレクトリに設定するまで、ファイル添付は無効です。この設定は、Apple Tools 経由の呼び出しを含め、下書きと送信の両方に適用されます。サーバーはシンボリックリンクを解決し、指定したディレクトリ内にある通常ファイルのみを受け付けます。そのディレクトリ外のファイル、ディレクトリ、および添付ファイルの転送区切り文字を含むパスは拒否されます。添付ファイルを含まない Mail 操作は、既存の安全性設定のまま引き続き利用できます。