io.github.epheterson/applemusic-mcp

Apple Music catalog. Actions: search, resolve, album_tracks, album_details, song_details, artist_details, genres, suggestions. `search` is discovery: one query in, a ranked list out, for browsing. `resolve` is identification: N identifiers in, N verdicts out, writing nothing — use it (never repeated `search`) to turn a track list into catalog IDs. It routes on which identifier you have: - `resolve(isrcs=...)` — exact, 25 per request. ISRCs come with Spotify/Rekordbox/ Plex exports; this is what keeps a large import under Apple's rate limit. - `resolve(tracks=...)` — titles/artists, fuzzy, reporting how confident each match is so a wrong edition gets caught before it's written. One request per track, so it's capped at 25 (raise with `max_tracks`, not `limit`). Either way the IDs come back ready for `playlist(action="add", track=...)` — or use `playlist(action="add", dry_run=True)` to preview against a specific playlist, which also reports what's already in it.

Config, cache, and authentication. Settings/cache actions: info, set-pref, list-storefronts, audit-log, clear-tracks, clear-exports, clear-audit-log. Auth actions (no terminal needed — just ask): - auth-status (or status): which tokens are active, expiry/auto-renew, what works, next step - signin: open a browser to sign in (any OS) and capture your session - logout: sign out — clears your user token + browser session so you can switch accounts (needs confirm=True) - reset: wipe ALL credentials for a clean slate or to drop a dev token for the web path; keeps your .p8 (needs confirm=True)

Personalized discovery. Actions: recommendations, heavy_rotation, personal_station, charts, top_songs, similar_artists, song_station.

Your library. Actions: search, add, recently_played, recently_added, browse, favorites (macOS), rate, remove, snapshot (macOS). action='search' searches the user's local library only — for catalog (Apple Music's full library) use catalog(action='search'). For search, types can be 'songs' (default), 'artists', 'albums', 'all', or 'genre' — types='genre' lists the user's own tracks whose genre matches query (e.g. query='Rock'); genre filtering is macOS-only (local Music app). Search returns one page: limit (default 25) caps results and offset pages through larger result sets — the text header shows 'start-end of total' so you know when more remain. action='favorites' lists songs marked Favorite (loved) in Music.app. action='add' adds catalog tracks/albums to your library over the API (developer token — generated or harvested — plus a media-user-token from `signin`); there is no UI-automation fallback. In api mode, search/browse read via the API and love/dislike rate via the API; star ratings (rate get/set) need native mode (local Music.app).

Playback transport. play/control/now_playing/settings run on the engine the `mode` preference resolves to — native Music.app (macOS), the Safari web player (macOS), or the Chrome web player (any OS). Override it for ONE call with `engine=`: 'native', 'safari', 'chrome', 'web' (the web engine — Safari on macOS, Chrome off-mac), or 'auto'. control/now_playing follow whichever engine is actively playing (so after a Safari queue, pause/next reach Safari). Safari needs a signed-in Safari + "Allow JavaScript from Apple Events"; Chrome needs a signed-in Chrome (`applemusic-mcp login`) + a desktop session. reveal and airplay are macOS-only. For the Up Next queue, use the separate `queue` tool. Actions: play, control, now_playing, settings, reveal, airplay.

Playlist and folder operations. Actions: list, folders (macOS — show the folder tree; folders are NOT in `list`), tracks, search, create, add, copy, move, path (macOS), remove, delete, rename. (move/remove/delete/rename work on every OS — via Music.app on macOS, via the web API on Windows/Linux. Only folders/path are macOS-only.) To find a playlist by name, use action='list' with filter='alice' (loose name match) rather than action='search', which searches the TRACKS inside a given playlist and needs a playlist param. Folders support slash-separated paths (e.g. 'Summer/Chill/Deep'). For action='add', `track` accepts a song NAME, a catalog song id (a numeric id like '1440857781' — pins the EXACT edition, avoiding name/album version mismatches), or a library id; set auto_add=True to find tracks not already in the user's library — this is required to add catalog songs the user doesn't own. Note: adding a not-yet-owned catalog track to a Music.app-made playlist is two-step — it's added to the library over the API, then attached locally once iCloud syncs it down (usually seconds). If the sync is slow it may return "added to your library — re-run to attach"; just re-run the same add. Rarely, if the sync stalls past ~20s, Music.app briefly flashes to the foreground as a last-resort sync nudge — expected, not a glitch. To SWAP one track for another, use action='add' with `replace`=<the old track to remove>: it adds the new track, confirms it actually persisted, and only THEN removes the old one — so if the add silently reverts (a Music.app bug), the old track is kept rather than lost.

The Up Next play queue — the web player's own MusicKit state (the same Up Next you see in the player). It runs on a web engine: Safari on macOS (no Chrome needed) or Chrome elsewhere, picked by your `mode` (auto/safari/chrome) or a per-call `engine=` ('safari' | 'chrome'). Using the queue makes it the active playback engine, so transport controls reach it. Native (Music.app) mode has no Up Next — set mode to safari/chrome or pass engine='safari'. Actions: - `list` — show Up Next (▶ marks the current item; indices are 0-based) - `set` — replace the whole queue in order, one call (`track`=comma/newline-separated ids or names) - `play_next` — insert a track right after the current one (`track`=name or catalog id, optional `artist`) - `play_last` — append a track to the end of Up Next - `remove` — remove the item at `index` (can't remove the currently-playing item — jump away first) - `clear` — empty the queue - `jump` — jump playback to a track: by `track` (name or catalog id — drift-proof, preferred since Up Next auto-advances) or by `index` - `autoplay` — set Autoplay (∞: keep playing similar music when the queue ends); pass `enabled=true` or `enabled=false` (required)