使用说明
applemusic-mcp
MCP server for Apple Music. It gives any MCP client (Claude, Cursor, Cline, Windsurf) control of your playlists, library, catalog, discovery, playback, and the Up Next queue. Runs on macOS, Windows, and Linux.
A Mac or an Apple Music subscription is all you need.
"Create a playlist called Road Trip and fill it with upbeat 90s alternative." · "Play my workout playlist on shuffle, and queue up Bohemian Rhapsody next." · "What have I been listening to lately, and what's topping the charts?"
Choose how much it can reach
You decide what this server may touch, in your MCP client's config. The assistant can't change it, and tools that need more than you allowed aren't offered to it at all.
--level |
It can reach | Good for |
|---|---|---|
music |
Only the Music app on your Mac. No network, no browser. | Your library, playlists, playback, ratings, AirPlay |
api |
+ Apple's music service over the internet | Searching and adding from the full catalog, recommendations, Windows and Linux |
web |
+ a Safari or Chrome web player | The Up Next queue, and playback off the Mac |
full |
Everything, including clicking inside the Music app | Every feature, nothing to decide |
--allow-ui (with any level) |
+ clicking inside the Music app (macOS Accessibility) | Playing catalog songs with no sign-in |
Start with music and move up when you want a feature that needs more. Leaving --level off is the same as full for now, as before 0.21.
For a Mac app with a guided setup instead of a terminal command, consider the community fork secure-applemusic-mcp-for-osx.
Features
What each engine can do, and the level that turns it on. ✓ supported, ✗ not possible there, — not applicable.
| Capability | Music.app (macOS) · music |
Apple Music API (any OS) · api |
Web player (Safari / Chrome) · web |
|---|---|---|---|
| Catalog search / browse | ✓ | ✓ (+ tokenless resolve) | — |
| Recommendations / charts / suggestions | ✗ | ✓ | — |
| Library search / browse | ✓ | ✓ | — |
| Genre search | ✓ | ✗ | — |
| Recently played / added | ✓ | ✓ | — |
| Add catalog → library | ✓ | ✓ | ✓ (in-page POST) |
| Remove from library | ✓ | ✓ | — |
| Love / dislike | ✓ | ✓ | — |
| 1–5 star ratings | ✓ | ✗ | ✗ |
| Favorites list | ✓ | ✗ | ✗ |
| Playlist create / add / remove / rename | ✓ | ✓ | — |
| Playlist copy | ✓ | ✗ | — |
| Playlist delete | ✓ | ✓ (web token) | — |
| Folders: single level + move in/out | ✓ | ✓ | — |
Folders: nested paths / tree / path |
✓ | ✗ | ✗ |
| Playback: play song / album / playlist / URL | ✓ | — | ✓ |
| Controls: pause / stop / next / prev / seek | ✓ | — | ✓ |
| Settings: volume / shuffle / repeat | ✓ | — | ✓ |
| now_playing | ✓ | — | ✓ |
| Up Next queue: view / next / last / remove / jump / clear / autoplay | ✗ | — | ✓ |
| Reveal in app | ✓ | — | ✓ (navigates page) |
| AirPlay device select | ✓ | ✗ | ✗ |
| Library snapshot / integrity | ✓ | ✗ | ✗ |
| Works with no Apple account | ✓ | ✗ | ✗ |
| Cross-platform (Win/Linux) | ✗ | ✓ | ✓ |
Music.app's catalog search and catalog play click inside the app, so at a set level they also need --allow-ui. Playback and the queue in a web player need a desktop session: Safari on a Mac (nothing to install) or Google Chrome elsewhere. How the engines are picked and overridden: configuration.
Setup
Requirements: Python 3.10+, plus a Mac or an Apple Music subscription. On a Mac nothing else is needed. The Chrome web player (Windows, Linux, or opt-in on a Mac) needs Google Chrome.
Claude Code, one line:
claude mcp add "Apple Music" -- uvx applemusic-mcp serve --level music
Claude Desktop / Cursor / Cline / Windsurf, install once, then add the config block:
pipx install applemusic-mcp # or: pip install applemusic-mcp
playwright install chromium # the Chrome web player: Windows/Linux, or a Mac with the [browser] extra
{
"mcpServers": {
"Apple Music": {
"command": "applemusic-mcp",
"args": ["serve", "--level", "music"]
}
}
}
Change music to api or web to unlock more; on Windows or Linux start at api, since music needs a Mac. Config file locations, the Chrome web player on a Mac, and source installs: configuration.
Restart your client and try "List my Apple Music playlists" or "Play my favorites." On macOS the local library and playback work immediately. To add catalog music or run on any OS, sign in.
Sign in
Needed for api and web. Your password never touches this tool, and sign-in persists.
applemusic-mcp login # Mac: reads your signed-in Safari. Windows/Linux: opens Chrome
applemusic-mcp status # verify
On a Mac, sign in at music.apple.com in Safari first and turn on Safari's Develop → Allow JavaScript from Apple Events once; login tells you exactly what's missing. For bulk work (playlist imports, library migrations), use your own Apple developer token to avoid the shared rate limit. Details, the Chrome and developer-token paths, and which API each write uses: signing in.
Tools
Seven action-based tools keep the MCP context small. Each takes an action and routes to the right engine.
| Tool | Actions |
|---|---|
playlist |
list, folders, tracks, search, create, add, copy, move, remove, delete, rename, path (playlists and folders) |
library |
search, add, browse, favorites, recently_played, recently_added, rate, remove, snapshot |
catalog |
search, resolve, album_tracks, album_details, song_details, artist_details, genres, suggestions |
discover |
recommendations, heavy_rotation, charts, top_songs, similar_artists, personal_station, song_station |
playback |
play (track / album / playlist / URL), control, now_playing, settings, reveal, airplay |
queue |
list, set, play_next, play_last, remove, jump, clear, autoplay (Up Next — Safari on macOS, Chrome elsewhere; engine= to pick) |
config |
status, signin, logout, reset, set-pref, audit-log, clear-audit-log, list-storefronts |
Batching, importing playlists, dry runs, export formats and storefronts: usage patterns.
CLI
applemusic-mcp serve --level music # run the MCP server (your client calls this)
applemusic-mcp login # web sign-in (macOS: Safari; Windows/Linux: Chrome)
applemusic-mcp login --chrome # use the Chrome web player on a Mac
applemusic-mcp login --dev # your own Apple developer token (.p8)
applemusic-mcp logout # sign out (switch accounts)
applemusic-mcp status # auth status and permission level
applemusic-mcp reset --force # wipe credentials (keeps your .p8 key file)
applemusic-mcp reset --all --force # full uninstall: also removes the .p8, profile, and cache
Good to know
- Playing catalog songs in Music.app needs
--allow-ui, an unlocked screen and Accessibility permission. It clicks Play inside the app. Songs already in your library don't need any of this. Or, at--level web, setmode="safari"to play in Safari instead. - Safari playback needs one real click to start. The first time you play in a freshly-opened or reloaded Safari tab, the browser requires a genuine click before it will start audio (a standard autoplay rule — we don't fake it). Click ▶ once in the Apple Music tab, then play/pause/next all work hands-free. If a play command reports the queue is ready but the track sits at 0:00, that's this — give the tab one click.
- Brand-new playlists take a moment to be addable over the API (cloud propagation). Existing ones are immediate.
- If catalog actions start failing, re-run
applemusic-mcp login. A handful of user playlists silently revert AppleScript edits (known Music.app bug); the server detects and surfaces the rollback.
Star History
License
MIT · Unofficial community project — not affiliated with or endorsed by Apple. Uses your own Apple Music account for personal use; follow Apple's terms.
mcp-name: io.github.epheterson/applemusic-mcp
Credits
FastMCP · Apple MusicKit · Model Context Protocol
Built with ❤️ in California by @epheterson and Claude Code.
