Apple Music MCP
Provides tools for managing and controlling the local Apple Music app on macOS, including library inspection, playlist management, playback control, metadata editing, and audit history.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Apple Music MCP Create a playlist named 'Focus' from my top 20 most-played tracks."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 IDvaluesOpaque 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
Related MCP server: Apple Music
Requirements
macOS 13 or newer with the Music app
Python 3.11 through 3.13
An MCP client that supports stdio servers
uvfor the recommended installation
Install uv with Homebrew if necessary:
brew install uvInstall and run
From a source checkout:
uv sync
uv run apple-music-mcpAfter the package is published, it can be launched without a checkout:
uvx apple-music-mcpThe 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 |
| Check macOS, Music, JXA, and writable playlist support |
| Read current playback and track state |
| Read library and playlist counts |
| Page through playlists, kinds, parents, and capabilities |
| Resolve one playlist by persistent ID |
| Page through ordered playlist membership |
| Search, filter, sort, and page through local tracks |
| Resolve an ordered batch of persistent track IDs |
| Run deterministic library or playlist analysis |
Playback
Tool | Purpose |
| List AirPlay outputs and EQ presets |
| Play, pause, stop, seek, and navigate tracks |
| Set volume, mute, shuffle, repeat, EQ, and outputs |
Safe changes
Tool | Purpose |
| Validate changes and return a preview plus approval token |
| Read plan state without secret hashes |
| Cancel a pending plan |
| Apply an explicitly approved, still-current plan |
| Page through redacted persistent audit history |
| 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_tracksplaylist.rebuild,playlist.archive,playlist.restore,playlist.purgefolder.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.sqlite3The 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_DENIEDUNSUPPORTED_PLATFORMNOT_FOUNDREAD_ONLY_PLAYLISTVALIDATION_ERRORPLAN_EXPIRED,PLAN_NOT_PENDING,INVALID_APPROVAL_TOKENSTALE_PLANIRREVERSIBLE_CONFIRMATION_REQUIRED,PURGE_REQUIRES_TRASHMUSIC_TIMEOUT,MUSIC_ERROR,APPLY_FAILED
Development
uv sync
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv buildRead-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
Available Tools
18 toolsmusic_analyze_libraryARead-onlyIdempotent
Run deterministic library or playlist analysis without sending every track to the AI.
Inputs: kind (required), limit, playlist_id. Returns: ok, data, meta, warnings
music_apply_changesADestructive
Apply an approved plan after token, expiry, and optimistic concurrency checks.
Inputs: plan_id (required), approval_token (required), irreversible_confirmation. Returns: ok, data, meta, warnings
music_cancel_change_planB
Cancel a pending plan without changing Music.
Inputs: plan_id (required). Returns: ok, data, meta, warnings
music_control_playbackC
Control playback or play a local track/playlist by persistent ID.
Inputs: action (required), track_id, playlist_id, position_seconds. Returns: ok, data, meta, warnings
music_get_change_planARead-onlyIdempotent
Read a pending or completed plan without exposing approval token hashes.
Inputs: plan_id (required). Returns: ok, data, meta, warnings
music_get_library_summaryARead-onlyIdempotent
Return track and playlist counts without returning the full library.
Inputs: no named parameters. Returns: ok, data, meta, warnings
music_get_player_stateARead-onlyIdempotent
Return playback state, current track, position, volume, shuffle, repeat, and EQ.
Inputs: no named parameters. Returns: ok, data, meta, warnings
music_get_playlistARead-onlyIdempotent
Get one playlist by persistent ID.
Inputs: playlist_id (required). Returns: ok, data, meta, warnings
music_get_tracksARead-onlyIdempotent
Resolve up to 500 persistent track IDs while preserving request order.
Inputs: track_ids (required), fields. Returns: ok, data, meta, warnings
music_healthARead-onlyIdempotent
Check platform, Music availability, JXA connectivity, and writable object kinds.
Inputs: no named parameters. Returns: ok, data, meta, warnings
music_list_changesARead-onlyIdempotent
List persistent audit history without exposing stored before/after metadata.
Inputs: limit, cursor. Returns: ok, data, meta, warnings
music_list_playback_targetsARead-onlyIdempotent
List AirPlay outputs and EQ presets, including active selections.
Inputs: no named parameters. Returns: ok, data, meta, warnings
music_list_playlistsCRead-onlyIdempotent
List playlists with stable IDs, kinds, parents, counts, and mutation capabilities.
Inputs: kind, limit, cursor, parent_id, +1 more. Returns: ok, data, meta, warnings
music_list_playlist_tracksARead-onlyIdempotent
List a playlist's tracks in current order with opaque pagination.
Inputs: playlist_id (required), limit, cursor, fields. Returns: ok, data, meta, warnings
music_plan_changesB
Validate library mutations and return a 10-minute, single-use approval token.
Inputs: operations (required). Returns: ok, data, meta, warnings
music_plan_undoA
Create a normal preview-and-approval plan for the reversible part of a prior change.
Inputs: change_id (required). Returns: ok, data, meta, warnings
music_search_tracksCRead-onlyIdempotent
Search or browse local library tracks with metadata filters and stable IDs.
Inputs: sort, limit, query, cursor, +3 more. Returns: ok, data, meta, warnings
music_set_playback_optionsB
Set volume, mute, shuffle, repeat, EQ, and AirPlay output selection.
Inputs: options (required). Returns: ok, data, meta, warnings
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool has a clearly distinct purpose: plan lifecycle, library browsing, playback control, and health checks. The plan-related tools are differentiated by their role (create, read, cancel, apply, list, undo), and there is no ambiguity between similar names.
All tools follow a consistent snake_case verb_noun pattern prefixed with music_ (e.g., get_playlist, list_playlists, control_playback). The only slight deviation is music_health, but it's a conventional health-check noun and does not disrupt the overall pattern.
18 tools is slightly above the typical 3–15 range, but the count is justified by the domain's breadth (library, playback, change planning, and system health). Each tool serves a distinct function, and there is no redundancy or bloat.
The tool set covers the full lifecycle: library retrieval and search, playlist management, playback control and options, change planning with approval and undo, and audit history. No critical operations are missing for a comprehensive Apple Music server.
Maintenance
Related MCP Connectors
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP Spec Compliance MCP — audits any MCP server.json against the official Model Context Protocol
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceGives any MCP client control of Apple Music playlists, library, catalog search and discovery, playback, and the Up Next queue, driving Music.app, Safari, Chrome, or the web API across macOS, Windows, and Linux. A Mac or a signed-in subscription is enough, and the local library plus playback work with no account at all on macOS.-
- FlicenseNot gradedqualityAmaintenanceGives MCP clients control of Apple Music playlists, library, catalog, discovery, playback, and the Up Next queue across macOS, Windows, and Linux, using Music.app, Safari, the Apple Music API, or Chrome.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients to search and browse the Apple Music catalog, manage library items, ratings, favorites and playlists with nested folders, and control playback, volume, shuffle, repeat and the Up Next queue. Runs via native Music.app, Safari, Chrome, or the Apple Music web API, so it works on macOS, Windows and Linux with just a Mac or an Apple Music subscription.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients to search and manage Apple Music playlists, library, catalog, and discovery, plus control playback and the Up Next queue across macOS, Windows, and Linux. It works with either a Mac or an Apple Music subscription and can use native Music.app, Safari, Chrome, or the Apple Music API.-