applemusic-mcp

English | 简体中文

An MCP server that lets Claude (or any MCP client) control the Music app on macOS and analyze your library. Just talk to it:

"Play some Leehom Wang" "Make a playlist of the K-pop songs in my library" "What genres do I listen to most?" "Favorite every song in playlists 3, 2, 1, last track first, so Favorite Songs shows them in order"

Everything runs locally on your Mac through JavaScript for Automation (JXA). No Apple Developer account, no API keys, and nothing leaves your machine.

Features

Limits: search covers your library, not the full Apple Music catalog. Play counts are the lifetime totals the Music app keeps on this Mac, so there's no per-week history. If you mostly listen on your phone, counts may be low.

Related MCP server: Sound

Requirements

• macOS with the Music app (tested on a recent macOS, Apple Silicon)

• Claude Desktop or another MCP client

• uv. The installer sets it up for you.

Install

One-click

1. Download or clone this repo, e.g. into ~/Documents/applemusic-mcp.

2. Double-click install.command. If macOS blocks it, right-click > Open. It installs uv, runs a read-only self-test, and adds the server to Claude Desktop's config (it backs up the old config first).

3. When macOS asks whether the app may control Music, click OK.

4. Quit Claude Desktop with Cmd+Q, reopen it, and ask "What's playing?"

Manual

git clone https://github.com/bwu109-netizen/applemusic-mcp.git
cd applemusic-mcp
uv sync
uv run python scripts/smoke_test.py   # read-only check

Then add this to ~/Library/Application Support/Claude/claude_desktop_config.json, using your own paths (which uv):

{
  "mcpServers": {
    "apple-music": {
      "command": "/Users/you/.local/bin/uv",
      "args": ["run", "--directory", "/Users/you/applemusic-mcp", "python", "-m", "applemusic_mcp.server"],
      "env": { "PYTHONPATH": "/Users/you/applemusic-mcp/src" }
    }
  }
}

Troubleshooting

• "Not authorized to send Apple events": open System Settings > Privacy & Security > Automation and turn on Music for Claude (or your terminal).

• Server keeps disconnecting / No module named applemusic_mcp: if the project lives in an iCloud-synced folder like Documents, iCloud can break a .venv inside it. install.command keeps the venv in ~/.local/share/applemusic-mcp/venv instead. Re-run it.

• Changes to the code don't show up: Claude Desktop starts the server once. Quit it with Cmd+Q and reopen.

How it works

Claude ──MCP (stdio)──▶ server.py ──osascript -l JavaScript──▶ Music.app

• src/applemusic_mcp/jxa.py runs JXA via osascript. User input is passed as JSON in argv, never pasted into script source, so song titles with quotes can't break or inject code. Errors come back as readable MCP tool errors.

• src/applemusic_mcp/server.py defines the tools. Library reads use bulk property fetches (one Apple Event per property, not per track), so even large libraries stay fast.

• src/applemusic_mcp/stats.py is plain Python aggregation over a 5-minute library cache.

Development

uv sync
uv run pytest

The tests mock the Music app, so they run on Linux too (CI uses Ubuntu). They also run node --check on every generated JXA script to catch syntax errors before they reach a Mac.

PRs welcome. Ideas: Apple Music catalog search via MusicKit, AirPlay device selection, ratings, smart-playlist creation.

License

MIT