How to add Apple Music MCP to Windsurf

Give Claude full access to your Apple Music: search the catalog, browse your library, manage playlists, and explore listening history. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 32★ · stdio · oauth

Windsurf config for Apple Music MCP

git clone https://github.com/marioinghilleri/mcp-apple-music && cd mcp-apple-music && uv sync

{
  "mcpServers": {
    "apple-music-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp-apple-music",
        "mcp-apple-music"
      ]
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Apple Music MCP config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Apple Music MCP's tools become available to Cascade.

Before you start

Python 3.10+
uv (recommended) or pip
An Apple Developer account (free tier is fine) with a MusicKit key (.p8 file, Key ID, Team ID)
An active Apple Music subscription
Run the one-time setup wizard (mcp-apple-music-setup) to complete browser-based MusicKit JS OAuth

What Apple Music MCP can do in Windsurf

search_catalog

Search the Apple Music catalog (songs, albums, artists, playlists).

search_library

Search within your personal library.

get_library_songs

List songs saved in your library (paginated).

get_library_albums

List albums in your library (paginated).

get_library_artists

List artists in your library.

get_library_playlists

List all your playlists with IDs.

get_playlist_tracks

Get the tracks inside a specific playlist.

create_playlist

Create a new playlist.

Security

Requires an Apple Developer account (free tier is fine) with a MusicKit `.p8` key and an active Apple Music subscription. The `.p8` private key is used to sign the Developer Token locally and never leaves your machine. A one-time browser-based MusicKit JS OAuth flow obtains a Music User Token, stored locally at `~/.config/mcp-apple-music/config.json` with file permissions set to 600. Keep the `.p8` file safe — Apple only allows downloading it once.

Apple Music MCP + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Apple Music MCP config there under the "mcpServers" key and restart the client.

Is Apple Music MCP safe to use with Windsurf?

Can it control playback (play/pause/skip)?

No. Apple's REST API does not expose playback control; that requires native MusicKit frameworks (iOS/macOS) or MusicKit JS in a browser. The README suggests a companion tool (chrome-relay) for driving an open music.apple.com tab in Chrome.

Do I need a paid Apple Developer account?

No, the free Apple Developer tier is fine to create a MusicKit key. You do need an active Apple Music subscription.

Where are my credentials stored and is my key safe?

The Developer Token is signed locally with your .p8 key, which never leaves your machine. The Music User Token is stored at ~/.config/mcp-apple-music/config.json with 600 file permissions.

View repo Full Apple Music MCP page