apple-icloud-mcp

# apple-icloud-mcp

[![CI](https://github.com/chrischall/apple-icloud-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/chrischall/apple-icloud-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/apple-icloud-mcp)](https://www.npmjs.com/package/apple-icloud-mcp)
[![license](https://img.shields.io/npm/l/apple-icloud-mcp)](LICENSE)

A [Model Context Protocol](https://modelcontextprotocol.io) 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](https://github.com/chrischall/apple-swift-mcp) — it runs anywhere: Linux, Windows, a
container, or hosted on [mcp-host](#running-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](https://www.anthropic.com/claude). 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](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`](#troubleshooting) tells you which are working.

| Service | What you get | Credential | Cost |
|---|---|---|---|
| **Apple Music** (official API) | Catalog search, charts, your library, playlists (create, add tracks, folders), history, recommendations, Replay, ratings, favorites | Apple Developer key **+** a Music User Token | Apple Developer Program ($99/yr) + Apple Music subscription |
| **Apple Music** (web-player mode, opt-in, unofficial) | Everything above **plus** rename/delete playlists, remove/reorder/sort/dedupe tracks, move to folders, remove from library | The `media-user-token` cookie from music.apple.com | Apple Music subscription only |
| **iCloud Calendar** (CalDAV) | List/search events (recurring ones expanded), create/update/delete with correct time zones and recurrence, free-time finder | Apple ID + **app-specific password** | Free |
| **iCloud Contacts** (CardDAV) | Search, read, create, update (per-email/phone edits), delete, groups | Apple ID + app-specific password | Free |
| **iCloud Mail** (IMAP/SMTP) | List mailboxes, search, read (without marking read), send and reply, flag, move | Apple ID + app-specific password | Free |
| **Apple Maps** (Maps Server API) | Geocode, reverse geocode, place search, directions, ETAs, signed map-image URLs | Apple Developer key | Free up to 25,000 calls/day |
| **WeatherKit** | Current conditions, hourly/daily forecast, next-hour precipitation, severe-weather alerts | Apple Developer key + Services ID | Free up to 500,000 calls/month |
| **iTunes Search + charts** | Search/lookup songs, albums, podcasts (with episodes), apps, books, audiobooks; top charts | None | Free |

## 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](https://www.apple.com/legal/internet-services/itunes/), the
[iCloud Terms and Conditions](https://www.apple.com/legal/internet-services/icloud/) and, for the developer-key
services, the [Apple Developer Program License Agreement](https://developer.apple.com/support/terms/). 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](#confirmation-mcp_confirm_mode)), and [`APPLE_WRITE_MODE`](#write-protection-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

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

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

```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](https://github.com/chrischall/apple-icloud-mcp/releases) and fill
in the settings it asks for, or add the same `npx` entry to `claude_desktop_config.json`.

### From source

```bash
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](https://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](#not-supported-and-why)).

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

These three need a paid [Apple Developer Program](https://developer.apple.com/programs/) membership.

1. In [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list),
   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 —