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.