Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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-mcpTools
| 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.get_playlist_tracks | Get tracks in a playlist (paginated) | Read |
music.create_playlist | Create a playlist, optionally in a folder | 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 tracks to a playlist by ID | Write |
Environment Variables
| Variable | Default | Description |
|---|---|---|
APPLE_MUSIC_MCP_ENABLE_WRITES | false | Enable mutation tools (create, move, playback, add 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 apple-music-mcpThen 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:
- Open System Settings > Privacy & Security > Automation
- Find your terminal app (Terminal, iTerm2, VS Code, etc.)
- 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 buildIntegration Tests
Requires Music app running on macOS:
INTEGRATION=true bun test srcTroubleshooting
"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