apple-music-mcp

apple-music-mcp

  

MCP server for controlling Apple Music on macOS via AppleScript. Works with Claude Code, Codex CLI, Cursor, and any MCP-compatible client.

Tools

| Tool | Description | Read/Write | | ------------------------------------- | --------------------------------------------------- | ---------- | | music.capabilities | Report server capabilities and runtime flags | Read | | music.health | Check Music availability and automation permissions | Read | | music.list_folders | List folder playlists | Read | | music.list_playlists | List user playlists, optionally filtered by folder | Read | | music.get_now_playing | Get current track info and player state | Read | | music.search_library | Search library tracks by name/artist | Read | | music.find_tracks | Find tracks in a bounded 1,000-candidate window | Read | | music.get_playlist_tracks | Get tracks in a playlist (paginated) | Read | | music.create_playlist | Create a playlist, optionally in a folder | Write | | music.create_playlist_from_criteria | Create a playlist from a bounded criteria match | Write | | music.create_folder | Create a folder playlist, optionally nested | Write | | music.move_playlist | Move a playlist into a folder | Write | | music.playback_control | Play, pause, next, previous, toggle | Write | | music.add_tracks_to_playlist | Add unique track IDs with per-ID outcomes | Write | | music.remove_tracks_from_playlist | Remove every instance of each unique track ID | Write |

Track matching and bulk mutation results

music.find_tracks requires at least one text or numeric filter. It scans at most 1,000 candidate tracks and returns tracks, totalMatched, limit, scanned, and truncated. When truncated is true, totalMatched is a lower bound within the scanned window, not a full-library total. music.create_playlist_from_criteria reports the same scanned and truncated values; its matched field has the same lower-bound rule.

Add and remove requests reject duplicate track IDs. Add results contain playlistId, requested, added, addedTrackIds, missingTrackIds, and failedTrackIds. A missing ID was not found in the library; a failed ID was found but could not be duplicated.

Remove results contain playlistId, requested, removed, removedTrackIds, missingTrackIds, and failedTrackIds. Removal deletes every matching playlist instance, so removed can exceed removedTrackIds.length. Criteria-created playlists also report requested, addedTrackIds, missingTrackIds, and failedTrackIds.

Environment Variables

| Variable | Default | Description | | ------------------------------- | ------- | ----------------------------------------------------------------- | | APPLE_MUSIC_MCP_ENABLE_WRITES | false | Enable mutation tools (create, move, playback, add/remove tracks) | | APPLE_MUSIC_MCP_DRY_RUN | false | Mutation tools return dry-run payloads without modifying Music |

Setup (Recommended)

Codex CLI / Codex IDE extension

Add the server with the CLI:

codex mcp add apple_music -- npx -y @pallas-labs/apple-music-mcp

Then set safe timeouts in ~/.codex/config.toml (default tool timeout is 60s, but this server can take up to ~70s for large playlist operations):

[mcp_servers.apple_music]
command = "npx"
args = ["-y", "@pallas-labs/apple-music-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 90

[mcp_servers.apple_music.env]
APPLE_MUSIC_MCP_ENABLE_WRITES = "false"

If you want mutation tools, set:

[mcp_servers.apple_music.env]
APPLE_MUSIC_MCP_ENABLE_WRITES = "true"

Claude Code

Add the server with Claude CLI:

claude mcp add --transport stdio apple-music -- npx -y @pallas-labs/apple-music-mcp

--transport/--env options must come before the server name, and -- separates Claude flags from the server command.

Project-shared setup (.mcp.json):

{
  "mcpServers": {
    "apple-music": {
      "command": "npx",
      "args": ["-y", "@pallas-labs/apple-music-mcp"],
      "env": {
        "APPLE_MUSIC_MCP_ENABLE_WRITES": "false"
      }
    }
  }
}

To enable writes, set APPLE_MUSIC_MCP_ENABLE_WRITES to "true".

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "apple-music": {
      "command": "npx",
      "args": ["-y", "@pallas-labs/apple-music-mcp"],
      "env": {
        "APPLE_MUSIC_MCP_ENABLE_WRITES": "false"
      }
    }
  }
}

Hardened Read-Only (Codex)

For extra safety, keep writes disabled and hide mutation tools:

[mcp_servers.apple_music]
command = "npx"
args = ["-y", "@pallas-labs/apple-music-mcp"]
tool_timeout_sec = 90
disabled_tools = [
  "music.create_playlist",
  "music.create_playlist_from_criteria",
  "music.create_folder",
  "music.move_playlist",
  "music.playback_control",
  "music.add_tracks_to_playlist",
  "music.remove_tracks_from_playlist"
]

Permissions

This server uses AppleScript to control Music. macOS will prompt for automation permission on first use.

If you see permission_denied errors:

1. Open System Settings > Privacy & Security > Automation
2. Find your terminal app (Terminal, iTerm2, VS Code, etc.)
3. Enable Music under it

Development

Development requires Bun 1.3.14.

git clone https://github.com/parthmangrola/apple-music-mcp.git
cd apple-music-mcp
bun install --frozen-lockfile
bun run format:check
bun run lint
bun run typecheck
bun run test
bun run build

Integration Tests

Requires Music app running on macOS:

INTEGRATION=true bun test src

Troubleshooting

"Music app is not running or unavailable" The server auto-launches Music. If it fails, open Music manually first.

"Permission denied to control Music" See the Permissions section above.

"AppleScript command timed out" Large libraries can be slow. Bounded track discovery allows up to 120 seconds, while playlist listing allows up to 70 seconds. In Codex, set tool_timeout_sec = 130 for this server. If you still hit timeouts, run music.health first to warm up the connection.

Mutations are non-atomic AppleScript doesn't support transactions. Bulk operations may partially succeed. Inspect the returned added/removed, missing, and failed ID arrays instead of assuming the full request completed.

License

MIT