apple-icloud-mcp

apple-icloud-mcp

Claude を Apple のウェブサービス（Apple Music のプレイリスト、ライブラリ、カタログ、iCloud Calendar、Contacts、Mail、Apple Maps、WeatherKit、iTunes Search API）に接続する Model Context Protocol サーバーです。

Apple 独自のウェブ API と標準プロトコル（CalDAV、CardDAV、IMAP/SMTP）を使ってネットワーク経由で Apple と通信するため、apple-swift-mcp のような Mac 専用の Apple 連携とは異なり、Linux、Windows、コンテナー、または claude.ai コネクターとしての mcp-host 上など、どこでも実行できます。この 2 つは互いを補完します。apple-swift-mcp は Mac 自身のアプリ（Calendar、Reminders、Contacts、Mail、Messages、Notes、Photos、Maps、Music.app のプレイリスト）を操作し、apple-icloud-mcp はどこからでも Apple のウェブサービスにアクセスでき、Apple Music カタログ、WeatherKit、iTunes も利用できます。

メモ

非公式です。 このプロジェクトは Apple Inc. と提携、承認、または後援関係にありません。Apple、iCloud、Apple Music、Apple Maps、WeatherKit は Apple Inc. の商標であり、ここでは接続先のサービスを示す目的でのみ使用しています。

警告

AI が開発したプロジェクトです。 このコードベースはすべて Claude Code が構築し、現在も積極的に保守しています。実装を監査した人間はいません。使用する前に、すべてのコードとツールの権限を確認してください。

重要

実際の Apple アカウントでの検証はまだ行われていません。 すべてのリクエスト形式は Apple のドキュメントまたは Apple 独自のウェブクライアントに基づいており、実際の挙動を忠実に再現したテスト用データを使ったテストで確認していますが、ビルド環境には Apple の認証情報がありませんでした。初回の実行が実際の検証となります。まず apple_healthcheck を実行し、各呼び出しの根拠については docs/APPLE-API.md を参照してください。

できること

• 「Road Trip 2026 という名前で、80 年代のアップテンポな曲を 20 曲集めたプレイリストを作って」
• 「Taylor Swift の最新アルバムから上位 5 曲を Workout プレイリストに追加して」
• 「Chill プレイリストの重複を削除して、アーティスト順に並べ替えて」（ウェブプレーヤーモード）
• 「最近、繰り返しよく聴いている曲は何？」 ／ 「今年の Apple Music Replay を見せて」
• 「来週のカレンダーには何が入っている？」 ／ 「木曜の午後に空いている 1 時間を探して」
• 「歯医者の予約を金曜の午後 3 時に変更して」
• 「Jane の電話番号は？」 ／ 「Acme の Bob Lee（[email protected]）を連絡先に追加して」
• 「大家さんから未読メールは届いてる？」 ／ 「Sam からの最新メッセージに、行くと返信して」
• 「午後 5 時に空港まで車でどれくらいかかる？」 ／ 「Union Square の近くにあるコーヒーショップ」
• 「明日のシカゴは雨が降る？」
• 「ポッドキャスト Hard Fork を見つけて、最新エピソードを一覧にして」 ／ 「今、英国で人気のアルバムは？」

サービスと各サービスに必要なもの

すべてのサービスはオプションです。認証情報が設定されると、それぞれのサービスが有効になり、 apple_healthcheck でどのサービスが機能しているか確認できます。

サービス	利用できる機能	認証情報	費用
Apple Music（公式 API）	カタログ検索、チャート、ライブラリ、プレイリスト（作成、トラックの追加、フォルダー）、再生履歴、おすすめ、Replay、評価、お気に入り	Apple Developer キー と Music User Token	Apple Developer Program（年額 $99）+ Apple Music サブスクリプション
Apple Music（Web プレーヤーモード、オプトイン、非公式）	上記のすべて に加えて、プレイリストの名前変更・削除、トラックの削除・並べ替え・ソート・重複削除、フォルダーへの移動、ライブラリからの削除	music.apple.com の media-user-token Cookie	Apple Music サブスクリプションのみ
iCloud Calendar（CalDAV）	イベントの一覧表示・検索（繰り返しイベントは展開）、タイムゾーンと繰り返し設定を適切に処理した作成・更新・削除、空き時間の検索	Apple ID + App 用パスワード	無料
iCloud Contacts（CardDAV）	検索、読み取り、作成、更新（メールアドレス／電話番号ごとの編集）、削除、グループ	Apple ID + App 用パスワード	無料
iCloud Mail（IMAP/SMTP）	メールボックスの一覧表示、検索、既読にせずに読み取り、送信と返信、フラグ設定、移動	Apple ID + App 用パスワード	無料
Apple Maps（Maps Server API）	ジオコーディング、逆ジオコーディング、場所検索、経路案内、到着予定時刻、署名付き地図画像 URL	Apple Developer キー	1 日あたり 25,000 回まで無料
WeatherKit	現在の状況、時間別・日別予報、1 時間以内の降水量、悪天候警報	Apple Developer キー + Services ID	1 か月あたり 500,000 回まで無料
iTunes Search + チャート	曲、アルバム、ポッドキャスト（エピソードを含む）、アプリ、本、オーディオブックの検索・照会、トップチャート	なし	無料

要件

• Node.js 22 以降（ホスト型ランナーでは Node 26 を使用します）。
• 利用するサービスに必要なもの（上の表を参照）。

利用条件の確認

この MCP サーバーを使用することで、以下の事項を確認し、同意したものとみなされます。

1. アクセスするのは、お客様ご自身の Apple アカウントのみです。使用する認証情報は、お客様が提供したものに限られます。他の人のデータにはアクセスできません。また、共有環境にデプロイする場合も、各ユーザーの Apple ID はそれぞれのプロセス内に保持されます。

2. お客様の利用には Apple の規約が適用されます。Apple のサービスを直接利用する場合と同様です。特に、Apple メディアサービス利用規約、iCloud 利用規約、および開発者キーを利用するサービスについては、Apple Developer Program 使用許諾契約が適用されます。iCloud 利用規約では、*"スクリプトやウェブクローラーなどの自動化された手段によるサービスへのアクセスを含め、サービスを妨害または中断してはならない"*と定められています。ここでの iCloud への接続には、Apple がサードパーティ製アプリ向けに提供している方法、つまり CalDAV、CardDAV、IMAP/SMTP 経由のアプリ用パスワードを使い、アシスタントを使う人のペースで処理します。Apple Music のウェブプレーヤーモードは異なります。ブラウザーのセッションを使って Apple の非公開ウェブプレーヤー API にアクセスするため、Apple がいつでもブロックする可能性があるとしています。このモードは、お客様が有効にしない限りオフです。メンテナーが規約を確認した日付：2026-09-26。

**3. 個人利用に限ります。**このプロジェクトは Apple Inc. と提携、承認、または後援を受けていません。「Apple」、「Apple Music」、「iCloud」および関連する商標は Apple のものです。認証情報を共有したり、このツールで大量のデータを抽出したりしないでください。

**4. 書き込み操作は実際に反映されます。**参加者を含むカレンダーイベントを作成すると、iCloud から参加者に招待メールが送信されます。メールを送信すると実際に送信され、プレイリストや連絡先を削除すると実際に削除されます。これらの操作の前には確認が求められます（確認を参照）。また、APPLE_WRITE_MODEを設定すると、書き込みツールをすべて削除できます。

5. 技術的な影響（レート制限、サインインに繰り返し失敗した場合のアカウントロックなど）を含む、あらゆる結果について、お客様が全面的に責任を負います。

これはメンテナーによる誠意ある要約であり、法律上の助言ではありません。また、Apple の実際の規約を変更または置き換えるものではありません。

インストール

Claude Code

claude mcp add apple -- npx -y apple-icloud-mcp

次に、使用するサービスの環境変数をサーバーの env に設定します（認証情報の設定を参照）。たとえば、.mcp.json に次のように記述します。

{
  "mcpServers": {
    "apple": {
      "command": "npx",
      "args": ["-y", "apple-icloud-mcp"],
      "env": {
        "ICLOUD_USERNAME": "[email protected]",
        "ICLOUD_APP_PASSWORD": "abcd-efgh-ijkl-mnop",
        "DISPLAY_TZ": "America/New_York"
      }
    }
  }
}

Claude Desktop

最新リリースから .mcpb バンドルをインストールして、求められる設定を入力するか、同じ npx エントリーを claude_desktop_config.json に追加してください。

ソースからインストール

git clone https://github.com/chrischall/apple-icloud-mcp.git && cd apple-icloud-mcp
npm install && npm run build
cp .env.example .env   # fill in what you need
npm run dev

認証情報の設定

iCloud カレンダー、連絡先、メール — アプリ用パスワード

1. appleid.apple.com にサインインし、サインインとセキュリティ → アプリ用パスワードに進んで、パスワードを生成します（2 ファクタ認証を有効にする必要があります）。
2. ICLOUD_USERNAME（Apple ID のメールアドレス）と ICLOUD_APP_PASSWORD（xxxx-xxxx-xxxx-xxxx 形式のパスワード）を設定します。通常の Apple ID パスワードは使用できません。
3. Apple ID が @icloud.com または @me.com のアドレスではない場合は、ICLOUD_MAIL_ADDRESS に iCloud メールアドレスも設定してください（メールのみ）。

Apple ID のパスワードを変更すると、すべてのアプリ用パスワードが無効になります。動作していた設定で突然「認証情報が拒否されました」と表示される場合、通常はこれが原因です。明確な認証拒否が確認されると、サーバーはそのパスワードの送信を停止します。停止期間は 24 時間、またはパスワードを変更するまでです。再起動後も停止状態は維持されます（拒否された組み合わせのダイジェストを記録し、パスワード自体は保存しません）。これは、サインインに繰り返し失敗すると Apple ID がロックされる可能性があるためです。

リマインダーは利用できません。iOS 13 以降、iCloud リマインダーは CalDAV 経由で同期されなくなりました（非対応である理由を参照）。

Apple Developer キー — Apple Music（公式）、Apple Maps、WeatherKit

この3つを利用するには、有料の Apple Developer Program メンバーシップが必要です。

1. Certificates, Identifiers & Profiles で、 利用するサービスの識別子を作成します。Apple Music 用の Media ID、Apple Maps 用の Maps ID、 WeatherKit 用の Services ID です。
2. Keys でキーを作成し、Media Services (MusicKit)、MapKit JS、および／または WeatherKit にチェックを入れます。 1つのキーで3つすべてを利用できます。.p8 をダウンロードします（ダウンロードできるのは1回だけです）。
3. APPLE_TEAM_ID、APPLE_KEY_ID、APPLE_PRIVATE_KEY（.p8 の内容。複数行の PEM、\n エスケープを使った 1行の値、または base64 のいずれでも使用できます）を設定します。WeatherKit の場合は APPLE_WEATHERKIT_SERVICE_ID も設定します。サービスごとに別のキーを使うこともできます。その場合は APPLE_MUSIC_KEY_ID / APPLE_MUSIC_PRIVATE_KEY、APPLE_MAPS_…、APPLE_WEATHERKIT_… を使用します。

サーバーは有効期間の短いトークンに自ら署名します（Apple Music は12時間、Maps と WeatherKit は1時間）。

Apple Music — ライブラリ（公式 API）：Music User Token

カタログ検索には開発者キーだけで利用できます。ライブラリやプレイリストを利用するには、Music User Token も必要です。このトークンは、ブラウザーで対話的に MusicKit にサインインした場合にのみ Apple が発行します。開発者キーを設定した状態で、次を実行します。

npx apple-icloud-mcp music-auth

127.0.0.1 のページが開くので、Sign in with Apple Music をクリックすると、 APPLE_MUSIC_USER_TOKEN=… が表示されます。その値を APPLE_MUSIC_USER_TOKEN に設定します。有効期間は約6か月で、 発行元の開発者キーに紐づいており、Apple ID のパスワードを変更すると無効になります。

開発者キーを持っていない人（共有デプロイを利用する別の人）は、.p8 を必要としません。キーの 所有者が npx apple-icloud-mcp music-auth --print-developer-token --days 7 を実行し、表示された有効期間の短い トークンを渡します。その人は自分のマシンで APPLE_MUSIC_DEVELOPER_TOKEN=<that token> npx apple-icloud-mcp music-auth を実行して サインインし、表示されたユーザートークンを保管します。開発者トークンは自動的に有効期限が切れますが、ユーザートークンはサーバーのキーで引き続き機能します。

Apple Music — ウェブプレーヤーモード（オプトイン、非公式）

Apple の公式 API では、プレイリストの名前変更や削除、トラックの削除や並べ替え、ライブラリからの項目の削除はできません。 Apple のウェブプレーヤーでは可能です。ウェブプレーヤーモードでは、ブラウザーセッションを使って同じ非公開 API を利用します。

1. デスクトップブラウザーで music.apple.com にサインインします。
2. 開発者ツールを開き、→ Application/Storage → Cookies → https://music.apple.com の順に移動して、 media-user-token Cookie の値をコピーします。
3. その値を APPLE_MUSIC_WEB_USER_TOKEN に設定します。

ウェブプレーヤー独自の開発者トークンは music.apple.com から自動的に読み込まれ、キャッシュされます。このモードは Apple Developer アカウントがなくても利用できます。Apple のサポート対象外のため、予告なく動作しなくなる可能性があります。このモードが必要なツールは説明にその旨が記載され、各ツールの応答には、どのバックエンド（official または web）が処理したかが示されます。

ヒント

Mac では、ウェブプレーヤーモードが不要な場合があります。 apple-swift-mcp を使うと、Music.app のローカルライブラリで、Music 独自のスクリプト機能を通じて、同じプレイリストの編集（名前変更、削除、項目の削除、並べ替え、重複排除、フォルダーへの移動）ができます。トークンも開発者アカウントも必要ありません。すでにライブラリにある曲が対象なので、カタログの曲は先に追加する必要があります（ここでは apple_music_add_to_library を使用します）。

mcp-host での実行

パッケージには mint.yaml が含まれており、mcp-host は apple-icloud-mcp の登録時にこれを読み込みます。

• 所有者の設定（開発者キー、APPLE_WRITE_MODE、APPLE_SERVICES、MCP_CONFIRM_SECRET など）は、登録時の環境変数に設定します。秘密鍵と確認シークレットはシークレットとして保存してください。
• 個人ごとの情報（Apple ID、App 用パスワード、Music トークン、iCloud Mail アドレス、タイムゾーン、デフォルトのカレンダー、Apple Music のストアフロント）はすべて auth.fields として宣言されています。mcp-host は接続時に各ユーザーに入力を求め、回答をユーザーごとに記憶します。呼び出し元ごとに専用のプロセスとデータディレクトリが用意されます。
• 状態：dataDir には、少数の小さなファイル（セキュリティを参照）が保存されます。これにより、ゼロまでスケールダウンした後のコールドスタートを高速化し、取り消されたパスワードや使用済みの確認トークンが再起動後に再利用されるのを防ぎます。
• 送信先：このサーバーが呼び出す Apple のホストのみです（api.music.apple.com、amp-api.music.apple.com、music.apple.com、caldav.icloud.com、contacts.icloud.com、*.icloud.com、imap.mail.me.com、smtp.mail.me.com、maps-api.apple.com、weatherkit.apple.com、itunes.apple.com、rss.marketingtools.apple.com）。HTTPS 通信は Node 組み込みの fetch を使ってランナーのプロキシを経由します。IMAP と SMTP も同じプロキシを HTTP CONNECT で経由します。

タイムゾーン（DISPLAY_TZ）を指定してください。ランナーのタイムゾーンは UTC です。オフセットなしで指定した時刻（「3pm」など）は DISPLAY_TZ として解釈されます。また、独自のタイムゾーンを持たない（「浮動」する）カレンダーイベントも、呼び出しで渡される timeZone にかかわらず、DISPLAY_TZ として扱われます。確認トークンは再起動後もそのまま有効です。mcp-host は dataDir を持つ子プロセスに、子プロセスごとに安定したキー（MCP_HOST_CONFIRM_SECRET）を付与するため、子プロセスがアイドル状態になった後や再デプロイされた後でも、承認済みのプレビューを実行できます。使用済みトークンはディスクに記録されるため、再利用できません。所有者が設定した MCP_CONFIRM_SECRET は、ホストのキーより優先されます。

ツール

59 個のツールがあります。モードは、そのツールを登録する最も低い APPLE_WRITE_MODE の値です。確認は、最初に確認を求めるツールを示します（詳細）。🌐 は、ウェブプレーヤーモードが必要な Apple Music ツールを示します。

ヘルスチェック

ツール	機能	モード	確認
apple_healthcheck	Apple の各サービス（Apple Music、iCloud Calendar、Contacts、Mail、Apple Maps、WeatherKit、iTunes）の設定状況と接続状況を確認します。	read

Apple Music

ツール	機能	モード	確認
apple_music_search_catalog	テキストで Apple Music のカタログを検索し、曲、アルバム、アーティスト、プレイリスト、ミュージックビデオ、ステーションを探します。	read
apple_music_get_catalog_items	ID で Apple Music カタログの曲、アルバム、アーティスト、プレイリスト、ミュージックビデオ、ステーションを検索します。ISRC では曲／ミュージックビデオ、UPC ではアルバムも検索できます。	read
apple_music_get_charts	ストアフロントの Apple Music トップチャート（再生回数の多い曲、アルバム、プレイリスト、ミュージックビデオ）を取得します。ジャンルを指定することもできます。	read
apple_music_list_playlists	Apple Music ライブラリ内のプレイリストをアルファベット順に一覧表示するか、1 つのプレイリストフォルダーの内容（フォルダーとプレイリスト）を一覧表示します。	read
apple_music_get_playlist	ライブラリのプレイリスト（p.…）またはカタログのプレイリスト（pl.…）を 1 つ読み込み、収録曲を順番に表示します。	read
apple_music_list_folders	Apple Music ライブラリ内のプレイリストフォルダーを一覧表示します。トップレベル、または 1 つのフォルダー内のサブフォルダーを表示できます。	read
apple_music_search_library	テキストで Apple Music ライブラリ（カタログ全体ではありません）を検索し、曲、アルバム、アーティスト、プレイリスト、ミュージックビデオを探します。	read
apple_music_list_library	Apple Music ライブラリの内容を一覧表示します。すべての曲、アルバム、アーティスト、ミュージックビデオ（アルファベット順、ページ分割）、または最近追加した項目を表示できます。	read
apple_music_get_history	Apple Music の最近の再生履歴を取得します。最近再生した項目（アルバム、プレイリスト、ステーション）、最近再生したトラック（曲）、最近のステーション、またはヘビーローテーションを表示します。	read
apple_music_get_recommendations	Apple Music のパーソナルレコメンデーション（「あなたにおすすめ」「最近再生した項目」などのグループ）を取得します。各グループのタイトルと、含まれるアルバム、プレイリスト、ステーション（カタログ ID）を表示します。	read
apple_music_get_replay	Apple Music Replay の最新年、または指定した年のトップ曲、アルバム、アーティストを取得します（Apple が提供している場合は再生回数も表示します）。	read
apple_music_get_ratings	カタログ ID またはライブラリ ID ごとに、曲、アルバム、プレイリスト、ミュージックビデオ、ステーションをお気に入り登録または低評価しているかどうかを取得し、「お気に入り」「低評価」「なし」を返します。	read
apple_music_create_playlist	Apple Music ライブラリに新しいプレイリストを作成します。曲（カタログ ID またはライブラリ ID を最大 500 件、100 件ずつ追加）、説明、フォルダー、公開設定も指定できます（APPLE_WRITE_MODE=additive では使用できません）。	additive
apple_music_add_playlist_tracks	曲（カタログ ID またはライブラリ ID を最大 500 件）をライブラリのプレイリストの末尾に追加します。	additive
apple_music_create_folder	Apple Music ライブラリにプレイリストフォルダーを作成します。トップレベル、または別のフォルダー内に作成できます。	all
apple_music_add_to_library	カタログ ID で曲、アルバム、プレイリスト、ミュージックビデオを Apple Music ライブラリに追加します（種類ごとに最大 100 件）。	additive
apple_music_add_favorites	カタログ ID で曲、アルバム、プレイリスト、アーティスト、ミュージックビデオをお気に入り（Apple Music の星印）に登録します。お気に入りにした曲は「お気に入りの曲」プレイリストに追加されます。種類ごとに最大 100 件です。	additive
apple_music_set_rating	曲、アルバム、プレイリスト、ミュージックビデオ、ステーション（カタログ ID またはライブラリ ID）の評価を「お気に入り」「低評価」に設定するか、「なし」にして解除します。	all
apple_music_update_playlist 🌐	Apple Music ライブラリのプレイリスト名や説明を変更するか、公開／非公開を切り替えます。	all
apple_music_remove_playlist_tracks 🌐	ライブラリのトラック ID および／または 1 始まりの位置（apple_music_get_playlist から取得）を指定して、ライブラリのプレイリストからトラックを削除します。	all	はい
apple_music_reorder_playlist 🌐	ライブラリのプレイリスト内のトラックを並べ替えます。トラックの移動、並べ替え（名前、アーティスト、アルバム、リリース日、再生時間、追加日）、逆順への変更、重複の削除（各曲の最初のコピーを残す）、またはトラック ID の新しい完全な順序への置き換え（トラックを削除する場合があります）ができます。	all	はい
apple_music_move_playlist 🌐	ライブラリのプレイリストをプレイリストフォルダーに移動するか、トップレベル（「root」）に戻します。	all
apple_music_delete_playlist 🌐	ライブラリのプレイリストを削除します（曲はライブラリに残ります）。	all	はい
apple_music_remove_from_library 🌐	LIBRARY ID（apple_music_list_library／apple_music_search_library の i.…、l.…、p.…）で曲、アルバム、ミュージックビデオ、プレイリストを Apple Music ライブラリから削除します。一度に最大 50 件まで削除でき、プレビューには各項目の名前が表示されます。	all	はい
apple_music_remove_favorites 🌐	カタログ ID で曲、アルバム、プレイリスト、アーティスト、ミュージックビデオのお気に入り（星印）を解除します。種類ごとに最大 100 件です。	all

iCloud Calendar

ツール	説明	モード	確認
apple_calendar_list_calendars	iCloud カレンダー（イベントカレンダーのみ）の一覧を取得します。id、名前、色、イベントを追加できるかどうか、共有されているかどうか（shared：他の人から自分に共有されている、sharedByYou：自分から他の人に共有している）、新しいイベントのデフォルトの追加先を含みます。	読み取り
apple_calendar_list_events	指定した期間内の iCloud Calendar のイベント（予定、会議）を開始時刻順に一覧表示します。繰り返しイベントは個々の発生日時に展開されます。	読み取り
apple_calendar_search_events	指定した期間内の iCloud Calendar のイベントをテキストで検索します（タイトル、場所、メモを大文字・小文字を区別せずに照合）。fromDate（デフォルトは今日。過去の日付も指定可能）と、toDate または daysAhead（デフォルトは 30）を指定します。期間は最大 366 日です。	読み取り
apple_calendar_get_event	一覧取得または検索で返された id を使って、iCloud Calendar のイベントを完全な形で取得します（省略されていないメモ、参加者、アラート、平易な英語での繰り返しルールを含みます）。	読み取り
apple_calendar_create_event	iCloud Calendar のイベントを作成します。タイトル、startDate/endDate（時間指定のデフォルトは 1 時間。終日イベントの endDate は最終日）、場所、メモ、url、アラーム、繰り返し、参加者を指定できます。	追加	参加者がいる場合
apple_calendar_update_event	iCloud Calendar のイベントを変更します。title、startDate/endDate、isAllDay、場所、メモ、url（"" で消去）、アラーム、参加者（新しいリスト全体）、カレンダー（イベントの移動）を指定できます。	すべて	参加者がいる場合
apple_calendar_delete_event	iCloud Calendar のイベントを削除します。繰り返しイベントの場合、対象範囲として thisEvent（デフォルト。「#occ=」を含む id が示す 1 件）、futureEvents（そのイベントと以降すべて）、または allEvents（シリーズ全体）を指定します。	すべて	はい
apple_calendar_find_free_time	iCloud カレンダーから空き時間を探します。勤務時間（workdayStart/workdayEnd、デフォルトは 09:00～17:00。デフォルトでは平日のみ）内で、1 日ごとに minDurationMinutes（デフォルトは 30）以上の空き枠を検索します。	読み取り

iCloud Contacts

ツール	説明	モード	確認
apple_contacts_search	ユーザーの iCloud Contacts（アドレス帳）を、名前、ニックネーム、会社、役職、メールアドレス、電話番号の数字で検索します。必要に応じて、1 つの連絡先グループ内のみに絞り込めます。	読み取り
apple_contacts_get	apple_contacts_search から取得した id を使って、iCloud の連絡先を完全な形で取得します。名前、組織、役職、メールアドレス、電話番号、住所、URL（それぞれラベルと apple_contacts_update で対象にできる entryId を含む）、誕生日、メモなどを含みます。	読み取り
apple_contacts_list_groups	iCloud Contacts の連絡先グループ（例：Family、Work）を一覧表示します。各グループの id、名前、メンバー数を含みます。	読み取り
apple_contacts_create	iCloud Contacts に新しい連絡先を作成します。givenName、familyName、organization のいずれかが必要です。middleName、nickname、department、jobTitle、note、birthday（YYYY-MM-DD、または年なしの --MM-DD）、メールアドレス、電話番号、URL などのリストを任意で指定できます。	追加
apple_contacts_update	iCloud の既存の連絡先を直接編集します。スカラー項目（givenName、familyName、middleName、nickname、organization、department、jobTitle、note、birthday）は現在の値を置き換えます。"" で消去できます。	すべて
apple_contacts_delete	id を指定して、iCloud Contacts の連絡先を 1 件、すべてのデバイスから完全に削除します。	すべて	はい

iCloud Mail

ツール	内容	モード	確認
apple_mail_list_mailboxes	iCloud Mail のメールボックス（フォルダー）を一覧表示します。パス、名前、用途（受信トレイ、送信済み、下書き、ゴミ箱、迷惑メール、アーカイブ）と、デフォルトではメッセージ数および未読数を取得します。	読み取り
apple_mail_search	iCloud Mail のメールボックス（デフォルトは INBOX）内のメールを、送信者、受信者、件名、全文、受信日の範囲、未読状態、フラグの有無で検索します。	読み取り
apple_mail_get_message	uid（apple_mail_search の結果）で iCloud Mail のメッセージを 1 件取得します。ヘッダー（from、to、cc、reply-to、date、subject、message-id）、プレーンテキストの本文（テキスト部分がない場合は HTML を読みやすいテキストに変換）、切り詰められたかどうかを示すフラグ、添付ファイル…を返します。	読み取り
apple_mail_download_attachment	apple_mail_get_message から取得した 1 始まりのインデックスを使って、添付ファイルを埋め込みバイナリーリソースとしてダウンロードします。デフォルトは 10 MiB、最大 20 MiB で、メッセージを既読にすることはありません。	読み取り
apple_mail_send	iCloud Mail アドレスからプレーンテキストのメールを送信します（to/cc/bcc、件名、本文。添付ファイルなし）。	すべて	はい
apple_mail_update_flags	uid（apple_mail_search の結果から 1～100 件、1 つのメールボックス内）を指定して、iCloud Mail のメッセージを既読または未読にし、フラグを付けたり外したりします。	すべて
apple_mail_move	iCloud Mail のメッセージ（apple_mail_search の結果から 1～100 件、1 つのメールボックス内）を別のメールボックスに移動します。移動先には、apple_mail_list_mailboxes のパス、またはエイリアス（inbox、archive、trash、junk、sent、drafts）を指定します。	すべて

Apple Maps

ツール	内容	モード	確認
apple_maps_geocode	Apple Maps のジオコーディングを使って、住所または場所の名前を座標に変換します。	読み取り
apple_maps_reverse_geocode	Apple Maps のリバースジオコーディングを使って、緯度・経度から住所を検索します（例：「37.33,-122.01 はどこですか？」）。	読み取り
apple_maps_search	Apple Maps で場所を検索します。店舗、名所、住所、ランドマークなどが対象です（例：「コーヒー」「EV 充電器」「ゴールデンゲートブリッジ」）。	読み取り
apple_maps_directions	Apple Maps で 2 つの場所間の車、徒歩、自転車でのルートを検索します（住所または「lat,lng」）。	読み取り
apple_maps_etas	Apple Maps で 1 か所から最大 10 か所の目的地までの所要時間と距離をまとめて取得します。交通状況を反映した車、公共交通機関、徒歩、自転車に対応します（例：「この店舗のうち、車で最も近いのはどこですか？」）。	読み取り
apple_maps_lookup_place	場所 ID を使って Apple Maps の場所を検索します。ID は apple_maps_search、apple_maps_geocode、apple_maps_reverse_geocode の結果に含まれる id フィールドです。一度に 1～50 件を検索できます。	読み取り
apple_maps_snapshot_url	静的な Apple Maps 画像（PNG）への署名付きリンクを作成します。住所または「lat,lng」を中心に設定し、ピンを追加できます。各ピンには任意でラベル、色、1 文字の記号を設定できます。中心を指定しない場合、地図はピンに合わせて表示されます。	読み取り

WeatherKit

ツール	内容	モード	確認
apple_weather_get	Apple Weather（WeatherKit）から指定した場所の天気予報を取得します。現在の状況、時間ごとの予報（最大 240 時間）、日ごとの予報（最大 10 日間、次の 1 時間の降雨、悪天候警報（countryCode が必要）に対応します。	読み取り
apple_weather_get_alert	Apple Weather（WeatherKit）の悪天候警報について、id（countryCode を指定して呼び出した apple_weather_get の alerts[].id）を使って、公式の全文を改変せずに 1 件取得します。	読み取り

iTunes の検索とランキング

ツール	説明	モード	確認
apple_itunes_search	Apple アカウントやキーなしで、Apple の iTunes Store カタログ（曲、アルバム、アーティスト、ポッドキャストとポッドキャストのエピソード、オーディオブック、アプリ、電子書籍）を検索します。	読み取り
apple_itunes_lookup	Apple アカウントやキーなしで、ID（apple_itunes_search や Apple Music のリンクから取得した trackId／collectionId／artistId の値を1～200個）で iTunes Store のアイテムを検索します。または、UPC／EAN（アルバム）、ISBN（書籍）、bundleId（アプリ）のいずれか1つで検索します。	読み取り
apple_charts_get	Apple の最新ランキング（Apple アカウントやキーは不要）：Apple Music の再生回数が多い曲、アルバム、ミュージックビデオ、プレイリスト、上位のポッドキャスト、急上昇中のポッドキャストエピソード、上位の登録者限定チャンネル、無料／有料アプリと書籍のランキング、上位のオーディオブックを取得します。	読み取り

書き込み保護（APPLE_WRITE_MODE）

値	登録されるもの
none	読み取りツールのみです。
additive	読み取りに加えて、ご自身のアカウントに追加するだけの書き込みが可能です。非公開プレイリストの作成、トラックの追加、ライブラリ／お気に入りへの追加、イベント（参加者なし、他の人と共有していないカレンダー内）または連絡先の作成が含まれます。既存のものを変更または削除したり、誰かに送信したりすることはありません。
all（デフォルト）	すべてです。

モードが許可されていないツールは登録されないため、プロンプトや挿入された指示から呼び出すことはできません。 認識できない値の場合は、安全側に倒して none になります。APPLE_SERVICES（カンマ区切り：music、calendar、 contacts、mail、maps、weather、itunes）を設定すると、ツールを登録するサービスを絞り込めます。

確認（MCP_CONFIRM_MODE）

取り消せない操作、および他の人に届く操作を行う前に確認を求めます。対象は、メールの送信、イベント、連絡先、プレイリスト、ライブラリアイテムの削除、プレイリストのトラックの削除または並べ替え、参加者がいるイベントの作成または変更（iCloud から参加者にメールが送信されます）です。プロンプトを表示できるクライアント（Claude Code）では、MCP_CONFIRM_ELICITATION=off でない限り、直接確認を求めます。表示できないクライアント（claude.ai）では、2段階のフローになります。最初の呼び出しでは何も実行せず、プレビューと confirmToken を返します。そのトークンを指定して再度呼び出した場合にのみ実行され、途中で対象が変更されていると拒否されます。

変数	説明
MCP_CONFIRM_MODE	ask-user（デフォルト。再度呼び出す前に、モデルがお客様の承認を得る必要があります）、auto（プレビューを確認した後、モデルが確認できます）、refuse（常に拒否します）。認識できない値は refuse として扱われます。
MCP_CONFIRM_ELICITATION	on（デフォルト）または off です。off の場合はプロンプトを表示せず、MCP_CONFIRM_MODE に応じてすべてのクライアントが2段階のフローを使用します。プロンプトを表示できるとされているのに表示されないクライアント（ゲートされた呼び出しがハングします。opencode 2.0.x）に設定してください。それ以外の値では on のままです（stderr に警告が出ます）。
MCP_CONFIRM_TTL_SECONDS	トークンの有効期間（デフォルトは600秒）です。
MCP_CONFIRM_SECRET	トークン署名キーです。デフォルトではプロセスごとにランダムに生成されます（mcp-host では、絶対パスの MCP_DATA_DIR と同じ場所にある、ホストの子プロセスごとの MCP_HOST_CONFIRM_SECRET が代わりに使用されます）。トークンを再起動後も有効にするには設定してください。使用済みトークンはディスク（mcp-utils の共有ストア、$MCP_DATA_DIR/.mcp-confirm/spent/、または絶対パスの MCP_DATA_DIR がない場合は ~/.apple-icloud-mcp/confirm-spent/）に記録され、再利用できません。APPLE_STATE_CACHE=false の場合はプロセス内でのみ記憶されます（その旨の警告が出ます）。ディレクトリに書き込めない場合は、トークンの再利用を防ぐため、確認済みの書き込みも拒否されます。

環境変数

すべて任意です。認証情報があるサービスは、それぞれ有効になります。空白、undefined、null、または展開されていない ${VAR} は未設定として扱われます。

Apple Developer キー

Variable	意味
APPLE_TEAM_ID	Apple Developer Team ID（10 文字）です。Apple Music（公式 API）、Apple Maps、WeatherKit に必要です。
APPLE_KEY_ID	Certificates, Identifiers & Profiles → Keys で作成し、Media Services（MusicKit）、MapKit JS、WeatherKit のいずれかまたはすべてを有効にした秘密鍵の Key ID です。
APPLE_PRIVATE_KEY 🔒	その鍵の .p8 ファイルの内容です（PEM 形式。\n エスケープを含む 1 行の値と base64 に対応しています）。
APPLE_PRIVATE_KEY_PATH	ローカルへのインストール時のみ使用します。APPLE_PRIVATE_KEY の代わりに指定する .p8 ファイルのパスです。
APPLE_MUSIC_KEY_ID	Apple Music 用の APPLE_KEY_ID のサービス別オーバーライド（APPLE_MUSIC_PRIVATE_KEY と組み合わせます。省略可能です）。
APPLE_MUSIC_PRIVATE_KEY 🔒	Apple Music 用の APPLE_PRIVATE_KEY のサービス別オーバーライドです（省略可能）。
APPLE_MAPS_KEY_ID	Apple Maps 用の APPLE_KEY_ID のサービス別オーバーライドです（省略可能）。
APPLE_MAPS_PRIVATE_KEY 🔒	Apple Maps 用の APPLE_PRIVATE_KEY のサービス別オーバーライドです（省略可能）。
APPLE_WEATHERKIT_KEY_ID	WeatherKit 用の APPLE_KEY_ID のサービス別オーバーライドです（省略可能）。
APPLE_WEATHERKIT_PRIVATE_KEY 🔒	WeatherKit 用の APPLE_PRIVATE_KEY のサービス別オーバーライドです（省略可能）。
APPLE_WEATHERKIT_SERVICE_ID	WeatherKit 専用です。WeatherKit 用に登録した Services ID です（例：com.example.weather）。

Apple Music

Variable	意味
APPLE_MUSIC_DEVELOPER_TOKEN 🔒	省略可能です。上記の鍵で署名する代わりに、事前に発行した Apple Music developer token（JWT）を指定します。
APPLE_MUSIC_USER_TOKEN 🔒	ライブラリ用の Music User Token（公式 API）です。MusicKit に一度サインインして取得します：npx apple-icloud-mcp music-auth。Apple Developer の鍵がない場合は、所有者に developer token（music-auth --print-developer-token）を依頼し、APPLE_MUSIC_DEVELOPER_TOKEN を設定して実行してください。有効期間は約 6 か月です。
APPLE_MUSIC_WEB_USER_TOKEN 🔒	オプトインの Web プレーヤーモード（developer account 不要。名前変更、削除、取り除く、並べ替えが可能になります）です。サインイン済みの music.apple.com タブから media-user-token cookie を取得します。
APPLE_MUSIC_WEB_DEVELOPER_TOKEN 🔒	Web プレーヤー用 developer token のオーバーライドです（省略可能。通常は music.apple.com から自動的に読み取られます）。
APPLE_MUSIC_STOREFRONT	Apple Music の 2 文字の storefront です（例：us、gb）。デフォルトはアカウントの storefront で、それがない場合は us です。

iCloud

Variable	意味
ICLOUD_USERNAME	iCloud Calendar、Contacts、Mail 用の Apple ID メールアドレスです。
ICLOUD_APP_PASSWORD 🔒	appleid.apple.com → Sign-In and Security → App-Specific Passwords で取得するアプリ用パスワードです（Apple ID のパスワードではありません）。
ICLOUD_MAIL_ADDRESS	Apple ID のメールアドレスが iCloud アドレスではない場合に限り、指定する @icloud.com アドレスです（Mail に必要です）。
ICLOUD_DEFAULT_CALENDAR	新しいイベントの登録先となるカレンダーです。指定がない場合は、最初の書き込み可能なイベントカレンダーが使われます（デフォルト）。

動作

変数	意味
APPLE_WRITE_MODE	"none" = 読み取り専用のツール。"additive" = 作成・追加も可能ですが、変更、削除、送信はできません。"all" = すべて（デフォルト）。認識されない値は安全側に倒して "none" になります。
APPLE_SERVICES	有効にするサービスをカンマ区切りで指定します（music、calendar、contacts、mail、maps、weather、itunes）。デフォルト：すべて。
DISPLAY_TZ	表示時刻と、オフセットを指定せずに入力した日付に使うIANAタイムゾーン（例：America/New_York）です。独自のタイムゾーンを持たずに保存された（浮動）カレンダーイベントは、常にこのタイムゾーンで読み取られます。カレンダー呼び出しの timeZone は、時刻の読み取り方と表示方法（作成・更新時はイベントの保存先タイムゾーンも）を変更しますが、浮動イベントの読み取り方は変更しないため、発生IDがこの値に依存することはありません。UTCで動作するホスト型サーバーでは、この値を設定してください。
APPLE_UNITS	天気に使う単位として "metric"（デフォルト）または "imperial" を指定します（マップの距離は常に両方の単位で表示されます）。
APPLE_STATE_CACHE	falseに設定すると、$MCP_DATA_DIR/.apple-icloud-mcp 配下には何も書き込みません。ウェブプレーヤーのトークンやiCloudの検出キャッシュは保存されず、拒否されたパスワードのラッチと使用済み確認トークンもプロセスが終了するまでしか保持されません。
APPLE_REQUEST_TIMEOUT_MS	リクエストごとのタイムアウト（ミリ秒）。デフォルトは30000です。
APPLE_DEBUG_LOG	1に設定すると、上流へのすべてのリクエスト行をstderrに記録します（認証情報は秘匿されます）。

確認

変数	意味
MCP_CONFIRM_MODE	claude.aiのようにプロンプトを表示できないクライアントで、確認が必要な書き込み（メール送信、削除、トラックの削除、招待）をどのように扱うかを指定します。"ask-user"（デフォルト：プレビューとconfirmTokenを表示し、モデルがユーザーのOKを得る必要があります）、"auto"、または "refuse" を指定します。不明な値の場合は拒否します。
MCP_CONFIRM_ELICITATION	"off" にすると確認プロンプトは表示されず、すべてのクライアントでMCP_CONFIRM_MODEのフローが使われます。プロンプトを表示できると言っているのに実際には表示しないクライアント（確認が必要な呼び出しが停止する場合。例：opencode 2.0.x）に設定してください。それ以外の値は "on" のままになり（stderrに警告が出ます）。
MCP_CONFIRM_TTL_SECONDS	confirmTokenの有効期間（秒）。デフォルトは600です。
MCP_CONFIRM_SECRET 🔒	confirmTokenの署名キーです。デフォルトではプロセスごとにランダムに生成されます。再起動または再デプロイの直前に発行したトークンも使えるように、この値を設定してください（使用済みトークンはディスクに記録されるため、再利用できません）。

🔒 = シークレットです。シークレットとして保管してください。

非対応の機能（およびその理由）

• リマインダー、メモ、「探す」、iCloud Drive、写真、メールを非公開。 いずれも公開APIまたは現在も使える標準プロトコルがありません。iCloudのリマインダーはiOS 13でCalDAVを終了しました。利用できるのはiCloud.comの非公開APIだけですが、Apple IDのパスワード全文、SRPサインイン、2要素認証コードが必要です。約2年間に4回も動作しなくなっており、高度なデータ保護によってブロックされます。また、iCloud利用規約で禁じられている「自動化された手段」そのものです。Macでは、apple-swift-mcpがリマインダー、メモ、写真をネイティブに扱えます。
• 音楽の再生。 AppleのウェブAPIでライブラリを管理できますが、再生はApple Musicアプリで行われます。
• カレンダーの作成または削除 — iCloudのCalDAVサーバーでは安定してサポートされていません。
• メール添付ファイルの送信 — 送信メールはプレーンテキストです。受信した添付ファイルは apple_mail_download_attachment でダウンロードできます。

トラブルシューティング

まず apple_healthcheck を実行してください。各サービスについて、認証情報が設定されているか（設定されていない場合は、設定すべき変数も）、Apple がその時点で認証情報を受け付けたか、現在の書き込みモード、表示に使用するタイムゾーンが報告されます。

同じチェックは、MCP クライアントを介さずにターミナルからも実行できます。サーバーを Claude に接続する前の確認や、認証情報の問題とクライアントの問題の切り分けに役立ちます。シェル環境のみを読み取り、.mcp.json の env ブロック、Claude Desktop の設定、または拡張機能の設定は読み取らないため、先に同じ値をエクスポートしてください。

printf 'App-specific password: '; read -rs ICLOUD_APP_PASSWORD; echo   # not echoed, kept out of shell history
export ICLOUD_APP_PASSWORD [email protected]
npx -y apple-icloud-mcp doctor                  # every enabled service
npx -y apple-icloud-mcp doctor calendar mail    # only these
npx -y apple-icloud-mcp doctor --json           # the apple_healthcheck report as JSON

設定済みのすべてのサービスが動作し、コマンドラインで指定されたすべてのサービスが設定済み、有効、かつ動作中の場合は終了コード 0、それ以外の場合は 1、使用方法に誤りがある場合は 2 で終了します。設定済みの各サービスに読み取り専用リクエストを 1 回送信します（iCloud のサービスは 1 つずつ処理するため、失効したパスワードが送信されるのは 1 回だけです）。機密情報は出力しません。ソースコードをチェックアウトしている場合は、node dist/index.js doctor でリポジトリの .env も読み取ります。

症状	考えられる原因
iCloud の「credentials rejected」	アプリ用パスワードが失効した（Apple ID のパスワードを変更した）か、通常のパスワードを使用しています。新しいアプリ用パスワードを生成してください。
Apple Music 401	デベロッパーキーの問題です。Team ID または Key ID が間違っているか、キーに MusicKit がありません。ウェブモードでは、media-user-token Cookie の有効期限が切れています。新しいものをコピーしてください。
Apple Music 403	Music User Token の有効期限が切れている（約 6 か月）、別のキーで生成された、またはアカウントに Apple Music のサブスクリプションがありません。music-auth を再実行してください（デベロッパーキーがない場合は、所有者に music-auth --print-developer-token を依頼してください）。
PLAYLIST_CHANGED	このサーバーがプレイリストに加えた最近の変更が、Apple 側でまだ反映されていない（読み取りが書き込みより数秒遅れる）か、プレイリストが別の場所で編集されました。このような読み取り結果に対して、並べ替え、トラックの削除、重複チェック付きの追加、プレイリストの更新は実行されません。apple_music_get_playlist で再読み込みしてから再試行してください。
時刻が数時間ずれている	DISPLAY_TZ に IANA タイムゾーンを設定してください。
ホスト型デプロイでメールがタイムアウトする	imap.mail.me.com / smtp.mail.me.com が送信先許可リストに含まれているか確認してください。

APPLE_DEBUG_LOG=1 を設定すると、すべてのアップストリームリクエスト行が、認証情報を伏せた状態で stderr に記録されます。

セキュリティ

• 認証情報は呼び出し時に環境から読み取られ、ディスクに書き込まれたり、ログに記録されたり、URL に含められたりすることはありません。すべてのエラー行とログ行から、このプロセスが使用したすべての認証情報が除去されます。

• Apple のホストにのみ接続します。認証情報が送信される前に、別の場所を指すリダイレクトや DAV の href は拒否されます。

• メールを読み取っても既読にはなりません（既読にするには apple_mail_update_flags を明示的に呼び出します）。HTML メールは隠しコンテンツを除いてテキストに変換されます。また、メールとカレンダーのテキストには、送信者からのコンテンツであることが明記されます。

• ローカルデータ： $MCP_DATA_DIR/.apple-icloud-mcp/（または ~/.apple-icloud-mcp/）に保存される小さなファイルです。すべてモード 0600 で、パスワードやトークンは含まれません。

  • music-web-token.json — Apple Music ウェブプレーヤー独自の公開デベロッパートークン（ウェブモードのみ）。
  • dav-calendar.json、dav-contacts.json — iCloud の検出 URL。取得元の認証情報に紐付けられています。
  • mail-login.json — iCloud が受け付けた IMAP ログイン形式。
  • icloud-rejected.json — 拒否された Apple ID とパスワードのソルト付きダイジェスト、および拒否された日時。再起動後も、失効したパスワードが 24 時間再送信されないようにします。
  • confirm-spent/ — 使用済みの確認トークンごとに 1 つのファイルを保存します（ランダム ID と有効期限）。再起動後も再使用されません。絶対パスの MCP_DATA_DIR を指定してホストしている場合は、代わりに mcp-utils の共有ディレクトリ $MCP_DATA_DIR/.mcp-confirm/spent/ に保存されます。

  削除するにはディレクトリを削除してください。または、これらのファイルを一切書き込まないようにするには APPLE_STATE_CACHE=false を設定してください（その場合、ラッチと使用済みトークンの記録はプロセスの実行中のみ保持され、その旨を警告します）。

開発

npm run build        # tsc → dist/, then esbuild bundle → dist/bundle.js
npm test             # typecheck + vitest
npm run test:coverage  # 100% line/branch/function/statement coverage is enforced

アーキテクチャについては CLAUDE.md を、Apple API の各詳細の出典については docs/APPLE-API.md を参照してください。

ライセンス

MIT