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=<that 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 APPLE_MUSIC_WEB_USER_TOKEN.

The web player's own developer token is read from music.apple.com automatically (and cached). This mode also works with no Apple Developer account. It is unsupported by Apple and may stop working without notice; the tools that need it say so in their descriptions, and their answers report which backend (official or web) served them.

[!TIP] On a Mac, you may not need web-player mode at all. apple-swift-mcp makes the same playlist edits — rename, delete, remove, reorder, sort, dedupe, move into folders — in the local Music.app library through Music's own scripting, with no tokens or developer account. It works on songs already in your library, so a catalog song still needs adding first (apple_music_add_to_library here).

Running on mcp-host

The package ships a mint.yaml that mcp-host reads when you register apple-icloud-mcp:

• Owner settings (the developer key, APPLE_WRITE_MODE, APPLE_SERVICES, MCP_CONFIRM_SECRET, …) go in the registration's environment — store the private key and confirm secret as secrets.
• Everything personal (Apple ID, app-specific password, Music tokens, iCloud Mail address, time zone, default calendar, Apple Music storefront) is declared as auth.fields, so mcp-host asks each person when they connect and remembers the answers per person; each caller gets their own process and data directory.
• State: dataDir holds a few small files (see Security) that keep a scale-to-zero cold start cheap and stop a revoked password or a spent confirmation token from being reused after a restart.
• Egress: only the Apple hosts this server calls (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 goes through the runner's proxy via Node's built-in fetch; IMAP and SMTP are tunnelled through the same proxy with HTTP CONNECT.

Give it your time zone (DISPLAY_TZ): the runner is on UTC, and times you give without an offset ("3pm") are read in DISPLAY_TZ — so are calendar events stored without a time zone of their own ("floating"), whatever timeZone a call passes. Set MCP_CONFIRM_SECRET too: without it, a confirmation token issued just before the child restarts (a redeploy, a machine move) stops working and you have to preview again. Spent tokens are recorded on disk, so a shared secret does not let one be replayed.

Tools

58 tools. Mode is the lowest APPLE_WRITE_MODE that registers the tool; Confirm marks tools that ask first (details); 🌐 marks Apple Music tools that need web-player mode.

Health

Apple Music

iCloud Calendar

iCloud Contacts

iCloud Mail

Apple Maps

WeatherKit

iTunes Search and charts

Write protection (APPLE_WRITE_MODE)

Gated tools are not registered at all below their mode, so no prompt or injected instruction can call them. An unrecognised value fails closed to none. APPLE_SERVICES (comma-separated: music, calendar, contacts, mail, maps, weather, itunes) narrows which services register tools at all.

Confirmation (MCP_CONFIRM_MODE)

Irreversible actions and anything that reaches another person ask for confirmation first: sending mail, deleting an event, contact, playlist or library item, removing or reordering playlist tracks, and creating or changing an event with attendees (iCloud emails them). A client that can show a prompt (Claude Code) asks you directly. One that cannot (claude.ai) gets a two-step flow: the first call does nothing and returns a preview plus a confirmToken; only a repeat call with that token acts, and it is refused if the target changed in between.

Environment variables

All optional; each service activates when its credentials are present. Values that are blank, undefined, null or an unexpanded ${VAR} count as unset.

Apple Developer key

Apple Music

iCloud

Behaviour

Confirmation

🔒 = a secret: store it as one.

Not supported (and why)

• Reminders, Notes, Find My, iCloud Drive, Photos, Hide My Email. None has a public API or a standard protocol that still works: iCloud Reminders left CalDAV with iOS 13. The only route is iCloud.com's private API, which needs your full Apple ID password, an SRP sign-in and a two-factor code, has broken four times in about two years, is blocked by Advanced Data Protection, and is exactly the "automated means" the iCloud Terms forbid. On a Mac, apple-swift-mcp covers Reminders, Notes and Photos natively.
• Playing music. Apple's web APIs manage your library; playback happens in an Apple Music app.
• Creating or deleting calendars — iCloud's CalDAV server does not reliably support it.
• Mail attachments — sending is plain text; reading lists attachments but does not download them.

Troubleshooting

Run apple_healthcheck first. For each service it reports whether credentials are configured (and which variables to set if not), whether Apple accepted them just now, the active write mode and the display time zone.

The same check runs from a terminal, with no MCP client involved — useful before wiring the server into Claude, or to tell a credential problem from a client problem. It reads the shell environment only, not the env block of .mcp.json, Claude Desktop's config or the extension's settings, so export the same values first:

printf 'App-specific password: '; read -rs ICLOUD_APP_PASSWORD; echo   # not echoed, kept out of shell history
export ICLOUD_APP_PASSWORD ICLOUD_USERNAME=you@icloud.com
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

It exits 0 when every configured service works (and every service named on the command line is configured, enabled and working), 1 otherwise, and 2 for a usage error. It sends each configured service one read-only request (the iCloud ones one at a time, so a revoked password is sent once), and prints no secrets. From a source checkout, node dist/index.js doctor also reads the repo's .env.

APPLE_DEBUG_LOG=1 logs every upstream request line to stderr, with credentials redacted.

Security

• Credentials are read from the environment at call time and never written to disk, logged, or put in a URL; every error and log line is scrubbed of every credential the process has used.

• Only Apple's hosts are contacted; a redirect or DAV href pointing anywhere else is refused before any credential travels.

• Reading mail never marks it read (apple_mail_update_flags does that when asked). HTML mail is converted to text with hidden content dropped, and mail and calendar text is labelled as content from its sender.

• Local data: small files under $MCP_DATA_DIR/.apple-icloud-mcp/ (or ~/.apple-icloud-mcp/), all mode 0600 and none holding your password or tokens:

  • music-web-token.json — Apple Music web player's own public developer token (web mode only);
  • dav-calendar.json, dav-contacts.json — iCloud discovery URLs, bound to the credential they came from;
  • mail-login.json — which IMAP login form iCloud accepted;
  • icloud-rejected.json — salted digests of rejected Apple ID/password pairs and when, so a revoked password is not re-sent for 24 hours even after a restart;
  • confirm-spent.json — digests of used confirmation tokens, so none can be replayed after a restart.

  Delete the directory to remove them, or set APPLE_STATE_CACHE=false to never write them (the latch and the spent-token record then last only as long as the process, and a warning says so).

Development

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

See CLAUDE.md for the architecture and docs/APPLE-API.md for the provenance of every Apple API detail.

License

MIT