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_healthcheckfirst, 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 [email protected] 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": "[email protected]",
"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
- Sign in at appleid.apple.com → Sign-In and Security → App-Specific Passwords → generate one (two-factor authentication must be on).
- Set
ICLOUD_USERNAME(your Apple ID email) andICLOUD_APP_PASSWORD(thexxxx-xxxx-xxxx-xxxxpassword). Your normal Apple ID password does not work here. - If your Apple ID is not an
@icloud.com/@me.comaddress, also setICLOUD_MAIL_ADDRESSto 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.
- 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.
- 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). - Set
APPLE_TEAM_ID,APPLE_KEY_IDandAPPLE_PRIVATE_KEY(the.p8contents — multi-line PEM, a one-line value with\nescapes, or base64 all work). For WeatherKit also setAPPLE_WEATHERKIT_SERVICE_ID. Separate keys per service are supported withAPPLE_MUSIC_KEY_ID/APPLE_MUSIC_PRIVATE_KEY,APPLE_MAPS_…andAPPLE_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:
- Sign in at music.apple.com in a desktop browser.
- Open the developer tools → Application/Storage → Cookies →
https://music.apple.comand copy the value of themedia-user-tokencookie. - 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_libraryhere).
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:
dataDirholds 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. Confirmation tokens survive a restart on their own: mcp-host gives a child with a
dataDir a stable per-child key (MCP_HOST_CONFIRM_SECRET), so a preview approved after the child idled out
(or was redeployed) still works. Spent tokens are recorded on disk, so none can be replayed. An owner-set
MCP_CONFIRM_SECRET takes precedence over the host's key.
Tools
59 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, unless MCP_CONFIRM_ELICITATION=off. 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 attachment sending — outgoing mail is plain text. Incoming attachments can be downloaded with
apple_mail_download_attachment.
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 [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
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_flagsdoes 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/— one file per used confirmation token (its random id and expiry), so none can be replayed after a restart. Hosted with an absoluteMCP_DATA_DIR, this lives in mcp-utils' shared$MCP_DATA_DIR/.mcp-confirm/spent/instead.
Delete the directory to remove them, or set
APPLE_STATE_CACHE=falseto 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