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.

See the 12-track curation demo: 22 grounded candidates become a three-act story, including a case where the numerically cheaper order damaged the narrative.

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  →  sequence with intent  →  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

Already use uv? Run the published package without a permanent install:

uvx --from apple-music-playlists am-playlist status
uvx --from apple-music-playlists am-playlist login
uvx --from apple-music-playlists am-mcp

For an MCP client, the equivalent Registry-aligned configuration is:

{ "mcpServers": { "applemusic": { "command": "uvx",
    "args": ["--from", "apple-music-playlists", "am-mcp"],
    "env": { "PYTHONIOENCODING": "utf-8" } } } }

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

Each title below opens the exact US catalog recording returned by the resolver, so the sequence can be auditioned rather than taken on trust.

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.