iCloud MCP

icloud-mcpは、2つの切り替え可能なバックエンドで7つのAppleサービスに対応しており、私たちの知る限り、この両方を備えたMCPサーバーはこれだけです。ローカルモードでは、AppleScriptを介してmacOSのネイティブアプリを操作します。認証情報もネットワークも不要で、iCloudプロトコルでは公開されていないサービス（リマインダー、メモ、メッセージ、Safari）にもアクセスできます。クラウドモードでは、代わりにIMAP/SMTP、CalDAV、CardDAVを使用するため、Mac以外のどのマシンでも実行できます。set-modeツールを使えば、再起動せずに実行時に2つのモードを切り替えられます。

機能

このサーバーは、メール、カレンダー、連絡先、リマインダー、メモ、メッセージ、Safariにわたって41個のツールを公開します。各ツールには、型付きスキーマ、人間が読めるタイトル、動作に関するアノテーションが付与されています。また、すべてのlist-*ツールは、テキスト出力とともに機械可読なstructuredContentを返します。ローカルモードではパスワードは一切不要で、macOSのオートメーション権限がその代わりとなります。

アクセスとセキュリティモデル

このサーバーは、標準入力／標準出力のみを介してJSON-RPCで通信します。ポートを開いたり、ソケットで待ち受けたりすることはありません。

認証情報がログに記録されることはありません。ICLOUD_APP_PASSWORDは起動時に一度だけ読み込まれ、IMAP/SMTP/CalDAV/CardDAVクライアントにのみ渡されます。診断情報では値そのものではなく、固定のマスクを表示します。パスワードの保管場所は任意です。手動でインストールする場合はモジュールと同じ場所にある.envファイルに、.mcpbバンドルを使う場合はホストがmacOSキーチェーンに保存する機密フィールドに保管できます。ローカルモードでは、パスワードはどこにもありません。macOSが独自のオートメーション許可プロンプトを通じてアプリごとにアクセスを管理するためです。許可はいつでも取り消せます。

すべてのツール引数は、ハンドラーの実行前にzodスキーマに照らして検証されます。また、AppleScriptへの各補間箇所で引数を強制的に型変換するため、数値でない値がスクリプトテンプレートに渡ることはありません。

プライバシーポリシー

このサーバーは何も収集せず、何も保持しません。テレメトリも、アナリティクスも、ディスク上の状態もありません。データは、お使いのマシン、接続先のAIクライアント、Appleのサービスの間でのみやり取りされます。収集、保存、第三者との共有、保持期間、連絡先について記載したポリシーの全文はPRIVACY.mdをご覧ください。

ツール

ローカル専用と記載されているツールは、iCloud プロトコルではそれらのサービスを利用できないため、クラウドモードではエラーを返します。

認証

• about
  • このサーバー、現在のモード、認証情報が設定されているかどうかに関する情報を返します
  • 入力なし
• check-auth-status
  • 現在のモードで認証情報を使用できることを確認します
  • 入力なし
• set-mode
  • 再起動せずにローカルとクラウドを切り替えます
  • 入力：mode（文字列、local または cloud）

メール

• list-emails：folder（文字列、省略可）、count（数値、省略可、最大 50）
• read-email：uid（文字列）、folder（文字列、省略可）
• send-email：to、subject、body（文字列）；cc、bcc（文字列、省略可）；isHtml（ブール値、省略可、クラウドモードのみ）
• search-emails：query、from、subject、folder（文字列、省略可）、unreadOnly（ブール値、省略可）、count（数値、省略可）
• mark-as-read：uid（文字列）、folder（文字列、省略可）、isRead（ブール値、省略可）
• list-folders：入力なし

カレンダー

• list-events：count（数値、省略可、最大 50）、daysAhead（数値、省略可）
• create-event：summary、start、end（文字列、ISO 8601）；description、location（省略可）；calendarUrl（クラウド）または calendarName（ローカル）
• update-event：eventUrl（文字列）；summary、start、end、description、location のいずれか。渡したフィールドのみが変更されます
• delete-event：eventUrl（文字列）
• list-calendars：入力なし

連絡先

• list-contacts：count（数値、省略可、最大 50）
• search-contacts：query（文字列）、count（数値、省略可）。名前、組織、メールアドレス、電話番号を検索します。電話番号の検索では書式を無視します
• read-contact：contactUrl（文字列）
• create-contact：displayName、firstName、lastName、email、phone、organization、title、notes（すべて省略可）
• delete-contact：contactUrl（文字列）
• list-contact-accounts：入力なし（ローカルのみ）
• list-contact-groups：accountId（文字列、省略可）（ローカルのみ）

リマインダー（ローカルのみ）

• list-reminder-lists：入力なし
• list-reminders：listName（文字列、省略可）、includeCompleted（ブール値、省略可）、count（数値、省略可）
• create-reminder：name（文字列）；body、dueDate、listName（省略可）；priority（数値 0～9、省略可）
• update-reminder：reminderId（文字列）；name、body、dueDate、priority のいずれか
• complete-reminder：reminderId（文字列）、completed（ブール値、省略可）
• delete-reminder：reminderId（文字列）
• search-reminders：query（文字列）、count（数値、省略可）

メモ（ローカルのみ）

• list-note-folders：入力なし
• list-notes：folderName（文字列、省略可）、count（数値、省略可）
• read-note：noteId（文字列）
• create-note：title（文字列）、body（文字列、省略可）、folderName（文字列、省略可）
• search-notes：query（文字列）、count（数値、省略可）

メッセージ（ローカルのみ）

読み取りには imsg CLI とフルディスクアクセスが必要です。

• list-chats：limit（数値、省略可）
• read-messages：chatId（数値）；limit（数値、省略可）；start、end（ISO 8601、省略可）；attachments（ブール値、省略可）
• send-message：to（文字列）、body（文字列）、file（文字列、省略可）
• react-message：chatId（数値）、type（love、like、dislike、laugh、emphasis、question）

Safari（ローカルのみ）

• list-safari-tabs：入力なし
• get-current-safari-url：入力なし
• open-safari-url：url（文字列）、inNewWindow（ブール値、省略可）
• close-safari-tab：windowIndex（数値、省略可）、tabIndex（数値、省略可）

ツールのアノテーション（MCP のヒント）

各ツールは、意図的に保守的な仕様のデフォルトに頼らず、動作を明示的に宣言しています。すべての list-*、read-*、search-*、get-* ツールに加えて、about と check-auth-status は読み取り専用としてマークされています。9 つのツールには destructiveHint が付いています。4 つの削除ツール（delete-event、delete-contact、delete-reminder、close-safari-tab）、取り消し不能な形で他の人に働きかける 3 つのツール（send-email、send-message、react-message）、その場で更新する 2 つのツール（update-event、update-reminder）です。ネットワークまたは他の人に働きかけるツールには openWorldHint が付いています。すべての Email と Calendar のツール、send-message、react-message、open-safari-url が該当します。読み取り専用ツールに加えて、mark-as-read、complete-reminder、update-reminder、update-event、set-mode は冪等としてマークされています。

インストール

Node.js 20 以降が必要です。

AI にインストールさせる

Claude、Claude Code、Cursor、ChatGPT、またはシェルや設定へのアクセス権を持つエージェントに、以下を貼り付けてください。

Install the iCloud MCP server. It is the npm package "mcp-icloud" (Node 20+),
stdio transport, server name "icloud", command "npx" with args ["-y", "mcp-icloud"].
On Claude Code run: claude mcp add --transport stdio icloud -- npx -y mcp-icloud
For other clients, add that command/args pair to the client's MCP config file.
Local mode (default) needs macOS; cloud mode needs env vars USE_LOCAL_MODE=false,
ICLOUD_EMAIL and ICLOUD_APP_PASSWORD (app-specific password from account.apple.com).
Docs: https://github.com/MrGo2/icloud-mcp

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "icloud": {
      "command": "npx",
      "args": ["-y", "mcp-icloud"]
    }
  }
}

クラウドモードの場合は、認証情報を追加します。

{
  "mcpServers": {
    "icloud": {
      "command": "npx",
      "args": ["-y", "mcp-icloud"],
      "env": {
        "USE_LOCAL_MODE": "false",
        "ICLOUD_EMAIL": "[email protected]",
        "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

Claude Code

claude mcp add --transport stdio icloud -- npx -y mcp-icloud

VS Code

この README の先頭にあるバッジを使うか、同じ command／args の組み合わせを MCP の設定に追加してください。

デスクトップ拡張機能（.mcpb）

Releases から .mcpb をダウンロードして開き、サイドロードしてください。このバンドルではモードの選択が求められます。クラウドモードの場合、アプリ用パスワードはファイルではなく macOS Keychain に保存されます。

権限とトラブルシューティング

macOS のオートメーションの確認ダイアログ（ローカルモード）

ツールがアプリに初めてアクセスすると、呼び出し元のプログラムにそのアプリの制御を許可するかどうかを macOS が確認します。この確認はツールごとではなく、アプリごとに一度だけ表示されます。確認ダイアログで許可するか、後から システム設定 → プライバシーとセキュリティ → オートメーション で許可してください。

確認ダイアログを閉じた場合、そのアプリへの呼び出しは認証エラー（osascript エラー -1743、「Apple イベントの送信が許可されていません」）で失敗します。macOS が自動的に再確認することはありません。オートメーションでチェックボックスを再度有効にするか、許可設定をリセットしてください。

tccutil reset AppleEvents

この操作を行うと、すべてのアプリのオートメーション権限が消去されるため、次回の使用時に確認ダイアログが再び表示されます。

フルディスクアクセス（メッセージの読み取り）

list-chats と read-messages は、フルディスクアクセスが必要な imsg CLI を使って Messages のデータベースを読み取ります。オートメーションの権限ではありません。サーバーを起動するプログラム（Claude Desktop、ターミナル、またはエディター）に、システム設定 → プライバシーとセキュリティ → フルディスクアクセス で権限を付与してください。権限がない場合、これらのツールはフルディスクアクセスが必要であることを報告します。

imsg が通常とは異なる場所にインストールされている場合は、明示的に指定してください。

export ICLOUD_MCP_IMSG_PATH=/opt/homebrew/bin/imsg

それ以外の場合、サーバーは ICLOUD_MCP_IMSG_PATH、IMSG_PATH、Homebrew の両方のプレフィックス、最後に PATH の順に検索します。

既知の制限事項：大容量のメールボックス

Mail.app のツールは AppleScript 経由でメッセージを順に処理します。非常に大きなメールボックスでは処理が遅く、結果が返る前に Apple Event のタイムアウトを超えることがあります。folder を指定して検索範囲を絞り、count を小さくするか、サーバー側で絞り込みを行うクラウドモードを使用してください。これは AppleScript ブリッジの特性であり、サーバー側で回避できるものではありません。

既知の制限事項：大量のカレンダーイベント

ローカルモードの list-events も、同様の AppleScript の制約を受けます。日付範囲はすでに whose クエリを使って Calendar.app 内で絞り込まれますが、カレンダーが多数あるアカウントでは、特に何年分ものイベントを含む購読カレンダー（祝日、スポーツの試合日程、旅行のフィード）で、クエリが現実的なタイムアウト時間を超えることがあります。list-calendars とイベントを書き込むツールには影響しません。計画中の EventKit バックエンドが実装されるまでは（#10 を参照）、イベントの読み取りにはクラウドモードを使用してください。CalDAV はサーバー側で絞り込みを行うため、規模を問わず高速です。

アプリ用パスワード（クラウドモード）

クラウドモードでは、アプリ用パスワードが必要です。通常の Apple ID パスワードは使えません。また、Apple は 2 要素認証が有効になっているアカウントにのみ、アプリ用パスワードを発行します。

1. appleid.apple.com にサインインします。
2. サインインとセキュリティ → アプリ用パスワード に移動します。
3. アプリ用パスワードを生成し、たとえば「iCloud MCP」という名前を付けます。
4. ICLOUD_EMAIL とともに、ICLOUD_APP_PASSWORD に設定します。

公開された場合は、同じページから無効にしてください。

サーバーが認識している状態の確認

現在のモードとサービス一覧を確認するには about を呼び出し、現在のモードで認証情報が使用可能かどうかを確認するには check-auth-status を呼び出します。

要件

• Node.js 20 以降
• ローカルモード：該当するアプリがインストールされた macOS。メッセージを読み取る場合は、imsg とフルディスクアクセスも必要です
• クラウドモード：任意の OS、2 要素認証が有効な iCloud アカウント、アプリ用パスワード。対象はメール、カレンダー、連絡先のみです

設定

変数	デフォルト	用途
USE_LOCAL_MODE	true	false にするとクラウドモードが選択されます
ICLOUD_EMAIL	（未設定）	iCloud アドレス。クラウドモードのみ
ICLOUD_APP_PASSWORD	（未設定）	アプリ用パスワード。クラウドモードのみ
ICLOUD_MCP_IMSG_PATH	（未設定）	imsg バイナリへの明示的なパス

環境変数、またはモジュールと同じディレクトリにある .env ファイルから読み込みます。.env.example を参照してください。

開発

サポート対象のパッケージマネージャーは pnpm です。コミット済みのロックファイルは pnpm-lock.yaml です。

pnpm install
pnpm test          # unit + contract suites, and a live stdio session
pnpm run inspect   # drive the server with the MCP Inspector

テストスイートでは osascript と imsg CLI をスタブ化しているため、実際のメール、カレンダー、メッセージのデータには触れず、どの OS でも実行できます。

ライセンス

MIT。詳しくは LICENSE を参照してください。