Apple Icloud MCP

apple-icloud-mcp

A Model Context Protocol server that connects Claude to Apple's web services: Apple Music (your playlists, library and the catalog), iCloud Calendar, Contacts and Mail, Apple Maps, WeatherKit, and the iTunes Search API.

It talks to Apple over the network through Apple's own web APIs and standard protocols (CalDAV, CardDAV, IMAP/SMTP), so — unlike Mac-only Apple integrations such as apple-swift-mcp — it runs anywhere: Linux, Windows, a container, or hosted on mcp-host as a claude.ai connector. The two complement each other: apple-swift-mcp drives the Mac's own apps (Calendar, Reminders, Contacts, Mail, Messages, Notes, Photos, Maps, and Music.app playlists), while apple-icloud-mcp reaches Apple's web services from anywhere and adds the Apple Music catalog, WeatherKit and iTunes.

[!NOTE]

Unofficial. This project is not affiliated with, endorsed by or sponsored by Apple Inc. Apple, iCloud,

Apple Music, Apple Maps and WeatherKit are trademarks of Apple Inc., used here only to name the services it

connects to.

[!WARNING]

AI-developed project. This codebase was entirely built and is actively maintained by

Claude Code. No human has audited the implementation. Review all code

and tool permissions before use.

[!IMPORTANT]

Not yet verified against a live Apple account. Every request shape comes from Apple's documentation or

Apple's own web client and is covered by tests against faithful fakes, but the build environment had no

Apple credentials. The first real run is the real verification — run apple_healthcheck first, and see

docs/APPLE-API.md for what each call relies on.

What you can do

• *"Make a playlist called Road Trip 2026 with twenty upbeat 80s songs"*
• *"Add the top 5 songs from Taylor Swift's latest album to my Workout playlist"*
• *"Remove duplicates from my Chill playlist and sort it by artist"* (web-player mode)
• *"What have I been listening to on heavy rotation?"* / *"Show my Apple Music Replay for this year"*
• *"What's on my calendar next week?"* / *"Find me a free hour on Thursday afternoon"*
• *"Move my dentist appointment to Friday at 3pm"*
• *"What's Jane's phone number?"* / *"Add Bob Lee from Acme with bob@acme.com to my contacts"*
• *"Any unread email from my landlord?"* / *"Reply to the last message from Sam saying I'll be there"*
• *"How long will it take to drive to the airport at 5pm?"* / *"Coffee shops near Union Square"*
• *"Will it rain in Chicago tomorrow?"*
• *"Find the podcast Hard Fork and list its latest episodes"* / *"What are the top albums in the UK right now?"*

Services and what each needs

Every service is optional: each one switches on when its credentials are present, and apple_healthcheck tells you which are working.

Requirements

• Node.js 22 or later (the hosted runner uses Node 26).
• Whatever the services you want need (table above).

Acknowledgement of Terms

By using this MCP server, you acknowledge and agree to the following:

1. It accesses your own Apple accounts only, with credentials you supply. It cannot reach anyone else's data, and on a shared deployment each person's Apple ID stays in their own process.

2. Apple's terms govern your use, just as they govern your direct use of Apple's services — in particular the Apple Media Services Terms, the iCloud Terms and Conditions and, for the developer-key services, the Apple Developer Program License Agreement. The iCloud Terms say you may not *"interfere with or disrupt the Service (including accessing the Service through any automated means, like scripts or web crawlers)"*. The iCloud paths here use the mechanism Apple provides for third-party apps — app-specific passwords over CalDAV, CardDAV and IMAP/SMTP — at the pace of a person using an assistant. Apple Music web-player mode is different: it uses Apple's private web-player API with your browser session, which Apple has said may be blocked at any time. It is off unless you turn it on. Terms read by the maintainer 2026-09-26.

3. Personal use only. This project is not affiliated with, endorsed by, or sponsored by Apple Inc. "Apple", "Apple Music", "iCloud" and related marks are Apple's. Do not share your credentials, and do not use this to bulk-extract data.

4. Writes are real. Creating a calendar event with attendees makes iCloud email them invitations; sending mail sends it; deleting a playlist or contact deletes it. Those actions ask for confirmation first (see Confirmation), and APPLE_WRITE_MODE can remove write tools entirely.

5. You accept full responsibility for the consequences, technical (rate limits, a locked account after repeated failed sign-ins) and otherwise.

This is the maintainer's good-faith summary, not legal advice, and it does not modify or supersede Apple's actual terms.

Installation

Claude Code

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

then set the variables for the services you want (see Setting up credentials) in the server's env, for example in .mcp.json:

{

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

Claude Desktop

Install the .mcpb bundle from the latest release and fill in the settings it asks for, or add the same npx entry to claude_desktop_config.json.

From source

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

Setting up credentials

iCloud Calendar, Contacts and Mail — an app-specific password

1. Sign in at appleid.apple.com → Sign-In and Security → App-Specific Passwords → generate one (two-factor authentication must be on).
2. Set ICLOUD_USERNAME (your Apple ID email) and ICLOUD_APP_PASSWORD (the xxxx-xxxx-xxxx-xxxx password). Your normal Apple ID password does not work here.
3. If your Apple ID is not an @icloud.com / @me.com address, also set ICLOUD_MAIL_ADDRESS to your iCloud Mail address (Mail only).

Changing your Apple ID password revokes every app-specific password — the usual reason a working setup suddenly returns "credentials rejected". After a definitive rejection the server stops sending that password — for 24 hours or until you change it, across restarts too (it records a digest of the rejected pair, never the password) — because repeated failed sign-ins can lock an Apple ID.

Reminders are not available: since iOS 13, iCloud Reminders no longer sync over CalDAV (see Not supported).

Apple Developer key — Apple Music (official), Apple Maps, WeatherKit

These three need a paid Apple Developer Program membership.

1. In Certificates, Identifiers & Profiles, create the identifiers for the services you want: a Media ID (Apple Music), a Maps ID (Apple Maps), and a Services ID for WeatherKit.
2. Under Keys, create a key and tick Media Services (MusicKit), MapKit JS and/or WeatherKit. One key can carry all three. Download the .p8 (you only get one chance).
3. Set APPLE_TEAM_ID, APPLE_KEY_ID and APPLE_PRIVATE_KEY (the .p8 contents — multi-line PEM, a one-line value with \n escapes, or base64 all work). For WeatherKit also set APPLE_WEATHERKIT_SERVICE_ID. Separate keys per service are supported with APPLE_MUSIC_KEY_ID / APPLE_MUSIC_PRIVATE_KEY, APPLE_MAPS_… and APPLE_WEATHERKIT_….

The server signs short-lived tokens itself (12 hours for Apple Music, 1 hour for Maps and WeatherKit).

Apple Music — your library (official API): a Music User Token

Catalog search works with the developer key alone. Your library and playlists also need a Music User Token, which Apple only issues through an interactive MusicKit sign-in in a browser. With the developer key set, run:

npx apple-icloud-mcp music-auth

It opens a page on 127.0.0.1, you click Sign in with Apple Music, and it prints APPLE_MUSIC_USER_TOKEN=…. Put that value in APPLE_MUSIC_USER_TOKEN. It lasts about six months, is tied to the developer key that minted it, and changing your Apple ID password revokes it.

Someone without the developer key (another person on a shared deployment) never needs the .p8. The key's owner runs npx apple-icloud-mcp music-auth --print-developer-token --days 7 and sends them the short-lived token it prints; they run APPLE_MUSIC_DEVELOPER_TOKEN= npx apple-icloud-mcp music-auth on their own machine, sign in, and keep the user token it prints. The developer token expires on its own; the user token keeps working with the server's key.

Apple Music — web-player mode (opt-in, unofficial)

Apple's official API cannot rename or delete playlists, remove or reorder tracks, or remove anything from your library. Apple's own web player can. Web-player mode uses that same private API with your browser session:

1. Sign in at music.apple.com in a desktop browser.
2. Open the developer tools → Application/Storage → Cookies → https://music.apple.com and copy the value of the `media-user-token` cookie.
3. Set it as `AP