Apple Music MCP Curator

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español | Português do Brasil | Deutsch | Français

Deep playlist curation for Apple Music: describe a feeling, scene, era, tension, or narrative arc; your agent turns it into a catalog-grounded selection whose versions, pacing, and transitions hold together as a listening experience.

Pure Python standard library — no pip install required to run, and no Apple Developer Program membership needed. Requires Python 3.10+ and works on Windows / macOS / Linux.

The primary interface is the local am-mcp stdio server. The language model already running in your MCP client interprets the brief and chooses candidates; this project searches the Apple Music catalog, resolves exact tracks, and performs account operations. There is no bundled model, LLM API key, artist list, or fixed theme. The CLI remains available for login, diagnostics, scripting, audits, and advanced sequencing.

  understand  →  curate  →  ground  →  shape the arc  →  dry-run  →  create

Why this project

• The brief stays semantic. The host LLM reasons directly about imagery, mood, lyrical angle, era, cultural context, contrast, and the role of each song. It is not reduced to a handful of user-supplied sliders or an opaque theme-fit number.
• Selection and sequencing stay separate. The model decides what belongs; measured BPM, key, energy, valence, and loudness can then diagnose transitions or refine order inside narrative blocks without overriding the musical idea.
• Every candidate is grounded. Catalog resolution catches missing tracks, duplicates, wrong artists, and suspicious live/remastered versions before the dry run and final create step.
• Listening evidence remains evidence. Replay history, recent plays, dates, and play counts can inform curation without silently becoming an algorithmic definition of the user's taste.
• Local and private by design. The server runs on your machine; credentials stay in the local app config, and there is no bundled model, telemetry service, or extra LLM API key.
• Portable MCP stdio. Works with Codex, Claude, Cursor, VS Code/Copilot, Gemini CLI, Windsurf, Cordis/DSH, Harness, and other clients that can launch a local stdio server.

Quick start

Recommended — install the MCP stdio service:

pip install apple-music-playlists
am-playlist status
am-playlist login       # one-time Apple ID sign-in

Register am-mcp in the client. The common configuration shape is:

{ "mcpServers": { "applemusic": { "command": "am-mcp",
    "env": { "PYTHONIOENCODING": "utf-8" } } } }

Then describe the result, not the implementation:

Create a 25-track late-night driving playlist: atmospheric alternative R&B and electronic, mostly from the last ten years, no live versions, with a calm landing.

Clients with MCP Prompt support can select create_playlist_from_description. In every other client, send the same request in chat: the server instructions and typed tools expose the same status → candidate pool → catalog grounding → direct comparison → dry-run → create workflow.

From a clone (nothing to install):

git clone https://github.com/Z-Han-Z/apple-music-playlists.git
cd apple-music-playlists

python am_playlist.py status     # auto-fetches the developer token
python am_playlist.py login      # one-time Apple ID sign-in (~6 months validity)

python am_mcp_server.py             # register this absolute script path in the MCP client

Installation also puts the CLI and MCP commands on your PATH:

am-playlist status      # the CLI
am-playlist login       # one-time Apple ID sign-in
am-mcp                  # the MCP stdio server

For development, pip install -e . from a clone makes edits take effect without reinstalling.

See SETUP.en.md for the credential walkthrough (three ways to get the user token, including a zero-dependency one).

A real curation demo: A Machine Dreams It Is Human

This is deliberately harder than “make me a workout playlist.” The brief asks music to carry a plot, and some of its constraints cannot be expressed as tempo or mood sliders:

Build a 12-track, three-act story in which a machine wakes in a city, mistakes attention for intimacy, asks to be touched, becomes vulnerable, and sees dawn. Cross electronic music and art pop from the late 1970s to the present; use one track per artist, studio recordings only, and let the voices become progressively more human. The ending must feel quiet and earned, not merely low-energy.

The run below used the public US Apple Music catalog on 2026-09-23. It did not read or write a private library.

22 LLM-proposed candidates
└─ 22 catalog matches returned exact title, artist, album, date, ISRC, and version metadata
   ├─ rejected: “Open Eye Signal (Mixed)” — resolved to a 2025 DJ Mix, not the studio cut
   ├─ rejected: “Deeper Understanding (2018 Remaster)” — not the requested original recording
   └─ 12 final selections

Final create dry-run:       12/12 matched; no write performed
Audio-feature coverage:     12/12 usable (100%)
Flow cost, narrative locks: 44.14 → 41.14

The interesting failure happened during ordering. With only the three acts locked, the numerical optimizer cut the measured cost from 48.28 to 14.88 — but put Retrograde after the dawn and made All Is Full of Love answer a request that had not happened yet. That is cheaper and worse. The host model therefore added semantic beat boundaries (request → answer, return → dawn) and let am_optimize_order make only local changes inside those boundaries. Selection and story stayed linguistic; BPM, key, energy, and valence remained supporting evidence.

[
  "The Robots - Kraftwerk",
  "Technopolis - Yellow Magic Orchestra",
  "Kid A - Radiohead",
  "Oblivion - Grimes",
  "Digital Witness - St. Vincent",
  "Is It Cold In The Water? - SOPHIE",
  "Touch - Daft Punk",
  "All Is Full of Love - Björk",
  "Cellophane - FKA twigs",
  "Retrograde - James Blake",
  "Long Road Home - Oneohtrix Point Never",
  "An Ending (Ascent) - Brian Eno"
]

This is the normal MCP workflow: the host model interprets the brief and proposes more candidates than it needs; am_resolve_candidates grounds them; the model chooses and assigns narrative roles; am_optimize_order optionally checks local flow without crossing semantic boundaries; and am_create_playlist(dry_run=true) verifies the exact final recordings before the write.

What's in the box

Supporting modules:

All three analysis modules are importable as libraries:

import playlist_flow, playlist_audit, playlist_optimize

print(playlist_flow.flow_report("My Playlist"))          # -> str
print(playlist_audit.audit_report("My Playlist"))        # -> str
ids, report = playlist_optimize.optimize("stack.json")   # -> (list[str], str)

MCP tools

The standard prompt create_playlist_from_description asks for a natural-language brief and optional name, track count, and response language. Curation stays in the host model; the tools are the grounded Apple Music execution layer:

am_status · am_search_songs · am_resolve_candidates · am_list_playlists · am_show_playlist · am_create_playlist · am_add_tracks · am_delete_playlist · am_audit_playlist · am_analyze_flow · am_optimize_order · am_recently_played · am_top_played

am_resolve_candidates grounds a generous LLM-proposed pool in real catalog metadata, flags duplicates and suspicious versions, and deliberately does not score theme fit. The host model compares candidates directly with the user's words and explains their playlist roles. am_analyze_flow diagnoses transitions; am_optimize_order can optionally refine ordering inside already chosen narrative blocks. It never decides which songs belong in the playlist.

Mount it in a Cordis agent preset with the template in preset/, or wire it into any other MCP client with:

{ "mcpServers": { "applemusic": {
    "command": "python", "args": ["/abs/path/am_mcp_server.py"] } } }

Complete tested examples for Codex, Claude, Cursor, VS Code/Copilot, Gemini CLI, Windsurf, Docker, Cordis/DSH, and Harness are in docs/client-setup.md.

Build the non-root local container with:

docker build -t apple-music-playlists:1.4.0 .

The client must run it attached with docker run --rm -i; mount only the app config directory and a writable cache as shown in the client guide. Config stays writable so token refresh can persist. Never bake Apple credentials into the image.

Tests

python -m unittest discover -s tests -v

The suite is entirely offline — no network, no credentials. Two kinds:

• Behaviour: the pure math that decides what "sounds good" — Camelot mapping, BPM folding, arc classification, each adjacency penalty asserted in isolation, annealing determinism and the block-order constraint. All six narrative archetypes must classify as themselves.
• Structural regressions, each pinned to a bug that actually shipped: no hardcoded catalog region, exactly one catalog_meta, no non-None --storefront default, cache outside the repo, every MCP tool wired to a handler, and the optimizer free of platform imports.

They earn their keep immediately — the suite caught a syntax error in a file written minutes earlier, before it was ever run.

The interesting part: audio features

Apple's catalog API exposes no audio features at all — no tempo, key, loudness, energy, or valence. Spotify's audio-features endpoint was shut off for new apps on 2024-11-27, and AcousticBrainz retired in 2022.

playlist_flow.py bridges the gap with a free, key-less chain built on ISRC, which Apple does return:

Apple Music track  ──►  ISRC
                          │
                          ├─► api.reccobeats.com/v1/track?ids=<ISRC>   → track UUID
                          │        └─► /v1/audio-features?ids=<UUID>
                          │                 → tempo, key, mode, loudness, energy, valence,
                          │                   danceability, acousticness, instrumentalness,
                          │                   liveness, speechiness
                          └─ (fallback) musicbrainz.org ISRC lookup

Results are cached locally, so the network cost is paid once per playlist.

Coverage is reported, never silently dropped. Every consumer prints a funnel saying why each track could not be measured:

Audio-feature coverage: 1,395/1,581 usable (88%)
  ·  80 tracks have no ISRC — the feature chain cannot start, so changing sources will not help
  · 106 tracks are not in the current source — switch sources or analyse the audio locally

That distinction is the point. No ISRC means the chain cannot start at all — a different feature source will not help. Not in the source means the ISRC is fine and switching sources (or analysing the audio locally) would fix it. Collapsing both into "missing features" discards the only information that tells you what to do next.

It matters more than it looks: tempo / key / energy / valence are the only things the adjacency rules and the arc can act on, so coverage is the ceiling on how good an ordering can be. At 60% coverage, four positions in ten were never evaluated — while the cost number still looks excellent. The optimizer therefore prints coverage above its cost lines, and warns below 90%.

Sequencing rules the optimizer enforces

Derived from the research collected in docs/ — including a PLOS ONE study in which 130 music professionals sequenced albums, and a randomized trial on mood-adaptive music ordering.

Hard adjacency rules

• No two slow tracks adjacent
• Avoid "only slightly slower" transitions (0–12% drop makes the slower track feel like it drags)
• Adjacent tracks must not be similar in both tempo and key
• No unjustified large BPM jumps (>40%); no jarring energy shifts under incompatible keys

These four have exactly one definition, in playlist_core.check_pair(), and both the audit and the optimizer call it. They used to be implemented twice, and the copies disagreed: the audit called a track "slow" below the tempo's 25th percentile while the optimizer used a fixed 100 BPM, and the audit never checked the BPM-jump rule at all. That is a tool diagnosing against one standard and repairing against another — so the count it reported could not be trusted.

Note on the "slow" threshold. It is absolute (100 BPM), not data-driven, deliberately: the optimizer evaluates the same sequence thousands of times while annealing, and a percentile threshold would drift as the permutation changes, so the cost would never settle. The cost is that a uniformly slow playlist flags every adjacent pair — that is real, not a sequencing failure, and the report says so.

Global arc — you choose the target shape:

python playlist_optimize.py stack.json --arc cinderella
python playlist_optimize.py --list-shapes

Six shapes: rags-to-riches, tragedy, man-in-a-hole (default), icarus, cinderella, oedipus. The target curve and the shape the audit classifies come from the same table in playlist_core.ARCHETYPES, so "what shape is this" and "what shape am I aiming for" cannot drift apart.

Tempo deliberately does not follow the chosen shape. The archetypes describe an emotional trajectory (valence / arousal); "put the fast ones in the middle" is a sequencing convention. Making tempo follow Cinderella too would conflate two independent principles.

Measuring this on a real arc playlist is what justified wiring it up: under man-in-a-hole — the shape the optimizer used to hardcode — that playlist's opening 30 tracks score an arc cost of 2.95, the worst of the six. The same tracks score 1.19 under cinderella. The tool had been aiming at the one shape that fit least.

The optimizer preserves your grouping (movements / eras / moods) and only reorders within groups, so thematic structure survives the loudness tuning. Drop the grouping and it reorders freely — measurably "smoother", at the cost of your narrative.

Example from a real run: cost 104.46 → 19.41 with grouping preserved, → 1.28 ungrouped.

Gotchas worth knowing before you debug

• Responses can be gzip-compressed even when you never sent Accept-Encoding. Decoding the raw bytes as UTF-8 yields garbage that looks like an empty body. (This is fixed in am_playlist.py.)
• DELETE only works on amp-api.music.apple.com. The documented host api.music.apple.com returns 401 for playlist and library-song deletion.
• Do not send x-apple-client-version to amp-api — it turns into a 500.
• Creating a playlist also adds its tracks to the library. Deleting the playlist does not remove them.
• BPM estimates have octave ambiguity (90 vs 180 for the same track). Fold into [70,160) before comparing, or "two slow tracks adjacent" over-reports by ~4×.
• Never pass "Title - Artist" straight into catalog search — you get live/remastered takes. Search on the space-separated form and score versions afterwards.
• An artist missing from a storefront's search ≠ the song is unavailable there. Look it up by ISRC.
• Only the client that created a playlist can modify it — Apple-side restriction.

More in docs/apple-music-api-notes.md and skill/reference.md.

Documentation

For the complete Simplified Chinese guide, see README_ZH_CN.md.

Community

• Contributing — development workflow, architecture boundaries, and review expectations
• Support — where to ask questions, report bugs, or propose features
• Code of Conduct — participation standards and private reporting route
• Security policy — supported versions and confidential vulnerability reporting

License

MIT — see LICENSE.

Unofficial community tooling. Not affiliated with or endorsed by Apple. Uses your own Apple Music account for personal use; follow Apple's terms of service.