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.

Quick Start

npx -y apple-music-mcp

Related MCP server: MCP AppleMusic Server

Tools

Environment Variables

Setup (Recommended)

Codex CLI / Codex IDE extension

Add the server with the CLI:

codex mcp add apple_music -- npx -y 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", "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 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", "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", "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", "apple-music-mcp"]
tool_timeout_sec = 90
disabled_tools = [
  "music.create_playlist",
  "music.create_folder",
  "music.move_playlist",
  "music.playback_control",
  "music.add_tracks_to_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

git clone https://github.com/parthmangrola/apple-music-mcp.git
cd apple-music-mcp
bun install
bun run format:check
bun run lint
bun run typecheck
bun test src
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. The server uses generous timeouts (up to 70s for playlist listing). In Codex, set tool_timeout_sec = 90 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 (like add_tracks_to_playlist) may partially succeed. This is a platform limitation.

License

MIT