Apple Music MCP

中文文档

A safe, structured Model Context Protocol server for the local Apple Music app on macOS. It lets an MCP client inspect a library, analyze and manage playlists, control playback, edit supported metadata, and keep a local audit trail. It does not call the online Apple Music catalog API and never exposes a network transport.

Highlights

• Structured JSON results with stable Music persistent ID values
• Opaque pagination for large libraries and playlists
• Deterministic duplicate, statistics, favorite, recent, stale, and play-count analysis
• Playlist and folder management, metadata updates, downloads, local imports, and exports
• Playback, volume, shuffle, repeat, EQ, and AirPlay control
• Mandatory preview/apply workflow for Music library writes
• Single-use, 10-minute approval tokens and optimistic concurrency checks
• Managed trash, persistent SQLite audit history, and best-effort undo
• No shell interpolation: Python passes bounded base64 JSON to one packaged JXA bridge

Requirements

• macOS 13 or newer with the Music app
• Python 3.11 through 3.13
• An MCP client that supports stdio servers
• uv for the recommended installation

Install uv with Homebrew if necessary:

brew install uv

Install and run

From a source checkout:

uv sync
uv run apple-music-mcp

After the package is published, it can be launched without a checkout:

uvx apple-music-mcp

The server communicates only over stdio. It does not bind a TCP port.

Codex configuration

For a local checkout, add this to ~/.codex/config.toml, replacing the path if needed:

[mcp_servers.apple_music]
command = "/Users/kz/Documents/Codex/2026-08-03/mcp-applemusic-py-https-github-com/work/apple-music-mcp/.venv/bin/apple-music-mcp"

For a published package:

[mcp_servers.apple_music]
command = "/opt/homebrew/bin/uvx"
args = ["apple-music-mcp"]

Claude Desktop configuration

{
  "mcpServers": {
    "apple_music": {
      "command": "/opt/homebrew/bin/uvx",
      "args": ["apple-music-mcp"]
    }
  }
}

On first use, macOS may ask whether the MCP client may control Music. Allow it in System Settings > Privacy & Security > Automation. The permission belongs to the host application that launched the MCP server, not to the Python package by itself.

Tools

Library and playlists

Tool	Purpose
music_health	Check macOS, Music, JXA, and writable playlist support
music_get_player_state	Read current playback and track state
music_get_library_summary	Read library and playlist counts
music_list_playlists	Page through playlists, kinds, parents, and capabilities
music_get_playlist	Resolve one playlist by persistent ID
music_list_playlist_tracks	Page through ordered playlist membership
music_search_tracks	Search, filter, sort, and page through local tracks
music_get_tracks	Resolve an ordered batch of persistent track IDs
music_analyze_library	Run deterministic library or playlist analysis

Playback

Tool	Purpose
music_list_playback_targets	List AirPlay outputs and EQ presets
music_control_playback	Play, pause, stop, seek, and navigate tracks
music_set_playback_options	Set volume, mute, shuffle, repeat, EQ, and outputs

Safe changes

Tool	Purpose
music_plan_changes	Validate changes and return a preview plus approval token
music_get_change_plan	Read plan state without secret hashes
music_cancel_change_plan	Cancel a pending plan
music_apply_changes	Apply an explicitly approved, still-current plan
music_list_changes	Page through redacted persistent audit history
music_plan_undo	Preview the reversible part of a previous change

The server also exposes the organize_library, clean_playlist, and build_playlist prompts, plus music://capabilities and music://safety resources.

Safe write workflow

All Music library writes use two calls. Planning reads the target state, validates object types and paths, and returns a short-lived token:

{
  "operations": [
    {
      "type": "playlist.create",
      "name": "Focused Work",
      "description": "Built from the local library",
      "track_ids": ["A1B2C3D4", "E5F6A7B8"]
    }
  ]
}

The client must show the preview to the user and receive explicit approval before passing the returned plan_id and approval_token to music_apply_changes. Apply re-reads every target and rejects the operation with STALE_PLAN if Music changed in the meantime.

Supported operation types:

• playlist.create, playlist.update, playlist.add_tracks, playlist.remove_tracks
• playlist.rebuild, playlist.archive, playlist.restore, playlist.purge
• folder.create, track.update, track.download, file.import, playlist.export

Ordinary user playlists and folders are writable. Library, Smart, Genius, subscription, and special playlists are read-only. Rebuilding an existing playlist creates a replacement with the requested order and archives the original, so the playlist persistent ID changes.

Archive moves an item into a server-managed MCP Trash folder. Permanent purge is accepted only for an item already inside that folder and requires the second confirmation phrase from the plan. The server never deletes a song from the Music library or its source file.

Metadata policy

track.update accepts common tags, sort tags, rating and favorite state, playback preferences, and classical work/movement fields. It rejects identifiers, file locations, artwork, account information, play/skip history, dates, and Music read-only fields. Large or incorrectly typed values are rejected during planning. Lyrics are omitted from default track results and returned only when lyrics is explicitly requested in fields.

Imports require existing absolute regular-file paths. Exports require an absolute path with an existing writable parent and refuse to overwrite by default. Import undo removes membership from the target playlist but deliberately leaves the imported library item in place.

Audit and privacy

Plan and change state is stored at:

~/Library/Application Support/apple-music-mcp/state.sqlite3

The directory and database are owner-only (0700 and 0600). History is pruned to 30 days and the latest 500 changes. Tool logs go to stderr and do not log full track lists, lyrics, or file contents. Stored before-values may include metadata needed for undo, so protect the macOS account and remove the database when history is no longer needed.

Undo is best effort. Membership can be restored, but Music may append restored tracks in a different order. Purge, downloads, and exports cannot be undone. Import undo does not remove the library item.

Error codes

Expected failures are returned in the normal structured result with ok: false and a stable error code. Common codes include:

• AUTOMATION_PERMISSION_DENIED
• UNSUPPORTED_PLATFORM
• NOT_FOUND
• READ_ONLY_PLAYLIST
• VALIDATION_ERROR
• PLAN_EXPIRED, PLAN_NOT_PENDING, INVALID_APPROVAL_TOKEN
• STALE_PLAN
• IRREVERSIBLE_CONFIRMATION_REQUIRED, PURGE_REQUIRES_TRASH
• MUSIC_TIMEOUT, MUSIC_ERROR, APPLY_FAILED

Development

uv sync
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv build

Read-only integration tests are marked integration. Isolated write tests are marked integration_write; they create uniquely named objects, retain their exact persistent IDs, and clean up only those objects. Neither group runs unless explicitly selected.

Limitations

• Local Music only; no Apple Music catalog search or MusicKit authentication
• No HTTP/SSE server mode
• No library-song deletion, transcoding, artwork writes, or Music window automation
• Music does not expose safe in-place track reordering; rebuilding changes playlist identity
• AirPlay and subscription behavior depends on current Music and account availability

License

MIT