apple-icloud-mcp 0.1.0 → 0.2.1

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Unofficial Apple Music, iCloud Calendar/Contacts/Mail, Apple Maps and WeatherKit tools for Claude Code",
-    "version": "0.1.0"
+    "version": "0.2.1"
   },
   "plugins": [
     {
@@ -14,7 +14,7 @@
       "displayName": "Apple iCloud",
       "source": "./",
       "description": "Apple Music playlists and library, iCloud Calendar, Contacts and Mail, Apple Maps, WeatherKit and iTunes search for Claude via MCP — runs anywhere, no Mac required. Unofficial; not affiliated with Apple.",
-      "version": "0.1.0",
+      "version": "0.2.1",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "apple-icloud",
   "displayName": "Apple iCloud",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Apple Music playlists and library, iCloud Calendar, Contacts and Mail, Apple Maps, WeatherKit and iTunes search for Claude via MCP — runs anywhere, no Mac required. Unofficial; not affiliated with Apple.",
   "author": {
     "name": "Chris Chall"

package/README.md

@@ -12,8 +12,9 @@ It talks to Apple over the network through Apple's own web APIs and standard pro
 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),
-while `apple-icloud-mcp` reaches Apple's web services from anywhere and adds Apple Music, WeatherKit and iTunes.
+`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,
@@ -210,6 +211,12 @@ works with **no** Apple Developer account. It is unsupported by Apple and may st
 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](https://github.com/chrischall/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`](mint.yaml) that mcp-host reads when you register `apple-icloud-mcp`:
@@ -228,7 +235,8 @@ The package ships a [`mint.yaml`](mint.yaml) that mcp-host reads when you regist
   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`. Set **`MCP_CONFIRM_SECRET`** too: without it, a confirmation token issued just before the
+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.
 
@@ -259,7 +267,7 @@ recorded on disk, so a shared secret does not let one be replayed.
 | `apple_music_get_recommendations` | Your personal Apple Music recommendations ("Made for You", "Recently Played" and similar groups), each with its title and the albums, playlists or stations in it (catalog ids). | read |  |
 | `apple_music_get_replay` | Apple Music Replay: your top songs, albums and artists for the latest Replay year, or for a given year (with play counts where Apple provides them). | read |  |
 | `apple_music_get_ratings` | Whether you have loved or disliked songs, albums, playlists, music videos or stations — catalog or library ids — returning love, dislike or none per id. | read |  |
-| `apple_music_create_playlist` | Create a new playlist in your Apple Music library, optionally with tracks (up to 500 catalog or library song ids; added 100 at a time), a description, a folder and public visibility. | additive |  |
+| `apple_music_create_playlist` | Create a new playlist in your Apple Music library, optionally with tracks (up to 500 catalog or library song ids; added 100 at a time), a description, a folder and public visibility (not in APPLE_WRITE_MODE=additive). | additive |  |
 | `apple_music_add_playlist_tracks` | Append songs (up to 500 catalog or library ids) to the end of one of your library playlists. | additive |  |
 | `apple_music_create_folder` | Create a playlist folder in your Apple Music library, at the top level or inside another folder. | additive |  |
 | `apple_music_add_to_library` | Add catalog songs, albums, playlists or music videos to your Apple Music library by catalog id (up to 100 per type). | additive |  |
@@ -341,7 +349,7 @@ recorded on disk, so a shared secret does not let one be replayed.
 | Value | What is registered |
 |---|---|
 | `none` | Read tools only. |
-| `additive` | Reads, plus writes that only **add** to your own account: create a playlist or folder, append tracks, add to library/favorites, create an event (without attendees, and not in a calendar shared with other people) or a contact. Nothing existing is modified or removed and nothing is sent to anyone. |
+| `additive` | Reads, plus writes that only **add** to your own account: create a (private) playlist or folder, append tracks, add to library/favorites, create an event (without attendees, and not in a calendar shared with other people) or a contact. Nothing existing is modified or removed and nothing is sent to anyone. |
 | `all` (default) | Everything. |
 
 Gated tools are not registered at all below their mode, so no prompt or injected instruction can call them.
@@ -409,7 +417,7 @@ All optional; each service activates when its credentials are present. Values th
 |---|---|
 | `APPLE_WRITE_MODE` | "none" = read-only tools; "additive" = also create/append, never modify, delete or send; "all" = everything (default). Unrecognized values fail closed to "none". |
 | `APPLE_SERVICES` | Comma-separated services to enable (music, calendar, contacts, mail, maps, weather, itunes). Default: all. |
-| `DISPLAY_TZ` | IANA time zone (e.g. America/New_York) for displayed times and for dates you give without an offset. Set this on a hosted server, which runs in UTC. |
+| `DISPLAY_TZ` | IANA time zone (e.g. America/New_York) for displayed times and for dates you give without an offset. Calendar events stored without a time zone of their own (floating) are always read in it: a calendar call's `timeZone` changes how your times are read and shown (and, on create/update, the zone an event is stored in) but never how a floating event is read, so occurrence ids never depend on it. Set this on a hosted server, which runs in UTC. |
 | `APPLE_UNITS` | "metric" (default) or "imperial" units for weather (Maps distances always show both). |
 | `APPLE_STATE_CACHE` | Set to false to write nothing under $MCP_DATA_DIR/.apple-icloud-mcp: no web-player token or iCloud discovery cache, and the rejected-password latch and spent confirmation tokens then last only as long as the process. |
 | `APPLE_REQUEST_TIMEOUT_MS` | Per-request timeout in milliseconds (default 30000). |
@@ -443,12 +451,29 @@ All optional; each service activates when its credentials are present. Values th
 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:
+
+```bash
+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`.
+
 | Symptom | Likely cause |
 |---|---|
 | iCloud "credentials rejected" | The app-specific password was revoked (Apple ID password changed) or the normal password was used. Generate a new app-specific password. |
 | Apple Music 401 | Developer key problem: wrong Team/Key ID, or the key lacks MusicKit. In web mode: the `media-user-token` cookie expired — copy a fresh one. |
 | Apple Music 403 | The Music User Token expired (≈6 months), was minted with a different key, or the account has no Apple Music subscription. Run `music-auth` again (without the developer key: ask its owner for `music-auth --print-developer-token`). |
-| `PLAYLIST_CHANGED` | Apple has not caught up with the previous playlist change yet (its reads lag writes by seconds), or the playlist was edited elsewhere. Re-read with `apple_music_get_playlist` and retry. |
+| `PLAYLIST_CHANGED` | Apple has not caught up with a recent change this server made to the playlist yet (its reads lag writes by seconds), or the playlist was edited elsewhere. Reorders, track removals, duplicate-checked adds and playlist updates refuse to act on such a read. Re-read with `apple_music_get_playlist` and retry. |
 | Times are off by hours | Set `DISPLAY_TZ` to your IANA zone. |
 | Mail times out on a hosted deployment | Check `imap.mail.me.com` / `smtp.mail.me.com` are in the egress allowlist. |