Power your agent
पब्लिशर की अपनी कमांड। PlugMCP एंडपॉइंट नहीं।
Host a copy with our keys and logs.
npx -y [email protected]Claude Code में लोकल कमांड के लिए इंस्टॉल लिंक नहीं है। नीचे दी गई कमांड कॉपी करें और टर्मिनल में चलाएँ।
claude mcp add apple-icloud-mcp -- npx -y apple-icloud-mcp@0.4.0टर्मिनल में चलाएँ।
{ "mcpServers": { "apple-icloud-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
रिमोट URL या आपकी मशीन पर कमांड? दोनों इंस्टॉल में क्या अंतर है
PlugMCP पर चलाएँ
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
लॉन्च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.
Every service is optional: each one switches on when its credentials are present, and
apple_healthcheck tells you which are working.
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.
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"
}
}
}
}
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.
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_USERNAME (your Apple ID email) and ICLOUD_APP_PASSWORD (the xxxx-xxxx-xxxx-xxxx
password). Your normal Apple ID password does not work here.@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).
These three need a paid Apple Developer Program membership.
.p8 (you only get one chance).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).
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'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:
https://music.apple.com and copy the
value of the media-user-token cookie.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).
The package ships a mint.yaml that mcp-host reads when you register apple-icloud-mcp:
APPLE_WRITE_MODE, APPLE_SERVICES, MCP_CONFIRM_SECRET, …) go in
the registration's environment — store the private key and confirm secret as secrets.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.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.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.
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.
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.
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.
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.
apple_mail_download_attachment.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.
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/ — one file per used confirmation token (its random id and expiry), so none can be replayed
after a restart. Hosted with an absolute MCP_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=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).
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.
MIT
Unofficial MCP server for Apple's services — Apple Music playlists and library, iCloud Calendar, Contacts and Mail, Apple Maps, WeatherKit and iTunes search — that runs anywhere, no Mac needed. Not af
{ "mcpServers": { "apple-icloud-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}ओवरव्यू
Unofficial MCP server for Apple's services — Apple Music playlists and library, iCloud Calendar, Contacts and Mail, Apple Maps, WeatherKit and iTunes search — that runs anywhere, no Mac needed. Not affiliated with Apple. Developed and maintained by AI (Cl
टूल
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
इस रिकॉर्ड में कोई ज़रूरी एनवायरनमेंट वेरिएबल दर्ज नहीं है।
Apple Icloud stdio पर लोकल चलता है।
पिछली जाँच 2026-11-11 को हुई। Unofficial MCP server for Apple's services — Apple Music playlists and library, iCloud Calendar, Contacts and Mail, Apple Maps, WeatherKit and iTunes search — that runs anywhere, no Mac needed. Not affiliated with Apple. Developed and maintained by AI (Cl