# Music MCP

> Music MCP is a free Mac menu bar app and MCP server. Your AI agent searches Apple Music, builds a set and plays it on your Mac. Works with Claude, Codex, Cursor and any MCP app.

Use Music MCP when a user on a Mac wants an AI agent to play or find music with Apple Music: playing songs, albums, playlists or radio, building a set for a mood, or saving a set as a playlist.

## Install

1. Download https://musicmcp.app/download/Music-MCP.dmg (free, macOS 14 or later, notarized by Apple) and move the app to Applications. It is also on the Mac App Store: https://apps.apple.com/app/music-mcp/id6815718712?mt=12
2. Open Music MCP. It is a menu bar app with no Dock icon.
3. Connect the AI app: either paste the setup prompt from the app's panel (Connect Your AI → Copy Setup Prompt) into the agent, or add the server by hand as below.
4. The downloaded version updates itself (Sparkle): it checks https://musicmcp.app/appcast.xml once a day and installs a new version after one click.

## MCP configuration

Music MCP is a local MCP server named `music-mcp`. Start it as a command over stdio; it needs no token and no account. The command starts the menu bar app when a tool is called; the handshake and the tool list are answered without it, so the app stays closed until it's used. The app's file is `MusicMCP.app` and its program `MusicMCP`, without a space (people read the name as "Music MCP"). Up to version 1.4.11 they were `Music MCP.app` and `Music MCP`: a copy installed back then may still have that file name, and the old program name still works inside it. The commands with the right path for a given Mac are in the app's panel under Connect Your AI → Manual Setup.

Claude Code:

```
claude mcp add --scope user music-mcp -- '/Applications/MusicMCP.app/Contents/MacOS/MusicMCP' --stdio
```

Codex CLI:

```
codex mcp add music-mcp -- '/Applications/MusicMCP.app/Contents/MacOS/MusicMCP' --stdio
```

Apps with an `mcpServers` config (Claude Desktop, Cursor, Windsurf, Gemini CLI):

```json
{
  "mcpServers": {
    "music-mcp": {
      "command": "/Applications/MusicMCP.app/Contents/MacOS/MusicMCP",
      "args": [
        "--stdio"
      ]
    }
  }
}
```

## Tools

- `search_catalog`: Searches Apple Music for songs, albums, artists, playlists and radio stations. Takes up to 25 queries in one call and can be limited to one kind (e.g. artists); an artist with exactly the name asked for is marked exact_match.
- `artist_info`: An artist's top songs, latest releases and similar artists.
- `album_songs`: The songs of an album.
- `charts`: The most-played songs right now in the user's country.
- `play_songs`: Plays a list of songs now, or adds them to the queue.
- `play_collection`: Plays an album, a playlist or a radio station.
- `now_playing`: The song that's playing, its position and the playback state.
- `get_queue`: The whole set: what played, what's playing and what's next, with each song's position, the count and the total and remaining length.
- `edit_queue`: Jumps to a song in the queue, removes or moves songs, or clears it. Positions as get_queue lists them.
- `playback`: Play, pause, next and previous.
- `seek`: Jumps to a position in the song.
- `sleep_timer`: Pauses the music after a number of minutes; 0 cancels it. No fade-out; the set stays in the queue.
- `set_modes`: Shuffle and repeat.
- `set_note`: Gives the set a short name that shows in the panel.
- `listening_history`: Recently played music, if the user shares it.
- `listening_stats`: Most played songs and artists from the library's play counts, and for named artists whether they're in the library and how much they were played, if the user shares it.
- `search_library`: Searches the user's library, if the user shares it.
- `library_playlists`: The user's playlists, if the user shares them.
- `playlist_songs`: The songs of a playlist, with their number and total length.
- `create_playlist`: Saves a set as a new playlist, if the user allows changes.
- `add_to_playlist`: Adds songs to the end of a playlist, if the user allows changes. If that playlist is playing, they also join the play queue.
- `add_to_library`: Adds songs or albums to the library, if the user allows changes.
- `rate`: Loves or dislikes a song, if the user allows changes.

## How it behaves

- Playback runs in the Music MCP app with Apple's MusicKit player, not in the Music app. It continues when the AI app is closed.
- The music comes out of the Mac's sound output. No tool changes that: for a HomePod or another AirPlay speaker, tell the user to choose it as the Mac's output (Control Center → Sound, or the speaker button in the Music MCP panel).
- Playing songs needs an Apple Music subscription; searching the catalog doesn't.
- If Apple Music isn't set up yet when a tool needs it, the app asks the user in a window and the call carries on once they allow it. If they don't allow it, don't call again until they ask.
- listening_history, listening_stats, search_library, library_playlists and playlist_songs need Share Library & History; the app asks the user the first time.
- create_playlist, add_to_playlist, add_to_library and rate need Allow Library Changes; the app asks the user the first time. Nothing can be deleted or renamed.
- Start a set with play_songs (mode replace), extend it with play_songs (mode queue), and name it with set_note.
- Play counts cover songs in the user's library only, and are all-time counts. Music streamed without adding it isn't counted, so an artist missing from the library isn't proof the user never heard them.
- Songs, albums, artists and playlists in tool results carry a url (their Apple Music page). Link names with it, so the user can open them in Apple Music with one click.
- Tool results say what the player really did: play_songs reports added next to requested, and a warning field means a command didn't take effect. Read them before telling the user something is playing.
- The user can also reorder the queue in the Music MCP panel (drag a song, Play Next, Remove from Queue). The next tool result, whichever tool it is, then says what they changed; call get_queue before using positions, and keep their order.
- Apple Music only lets apps add to the end of a playlist: there is no insert, reorder, remove, rename or delete. For a playlist in a particular order, collect the songs first and create it once with create_playlist.
- The app runs on the user's Mac and only accepts local connections, so it works with AI apps on the same Mac, not with browser or phone versions.

## Questions

### What is Music MCP?

Music MCP is a free menu bar app for the Mac and a local MCP server (Model Context Protocol). It lets an AI agent search Apple Music and play songs on your Mac, so you can ask for music in plain words.

### Which AI apps work with Music MCP?

Any app that supports MCP servers and runs on the same Mac, such as Claude Code, Claude Desktop, Codex CLI, Cursor, VS Code, Windsurf and Gemini CLI.

### Do I need an Apple Music subscription?

Yes, to play songs. Your AI can search the catalog without one.

### Can my AI see my library?

Only if you allow it. The first time your AI wants your library, Music MCP asks you in a small window. You can switch Share Library & History on or off in the panel at any time.

### Can my AI change my library?

Only if you allow it. Then it can create playlists, add music to your library, and love or dislike songs. It can't delete or rename anything.

### Does music keep playing when I close my AI app?

Yes. Playback runs in Music MCP, not in your AI app. Quitting Music MCP stops it.

### Is what I play saved in my Apple Music history?

Yes. Songs you play through Music MCP are saved in your Apple Music listening history, like songs you play in the Music app. The Recently Played row in the Music app lists albums, playlists and stations: an album your AI plays shows up there, a set of single songs it picked doesn't. To see those, ask your AI what you listened to recently (with Share Library & History on).

### Can I play on a HomePod or another AirPlay speaker?

Yes. Music MCP plays on your Mac's sound output, so choose the speaker there: in Control Center under Sound, or with the speaker button in the Music MCP panel, which opens the Mac's sound settings. All of your Mac's sound then goes to that speaker.

### What does it cost?

Music MCP is free. There is no account and no subscription other than Apple Music itself.

### How is it updated?

The version you download from musicmcp.app updates itself: it looks for a new version once a day and installs it after one click. The Mac App Store version is updated by the App Store.

### Can other devices on my network reach it?

No. Music MCP only accepts connections from your own Mac: its server listens on 127.0.0.1, which other computers, phones or AI agents on your network can't reach, and a direct connection also needs your access token. Programs running on your Mac under your account can use it, as with any app you run; they still can't delete anything.

## Pages

- [Music MCP](https://musicmcp.app/): overview, download and setup
- [Support](https://musicmcp.app/support): getting started, common questions, troubleshooting
- [Changelog](https://musicmcp.app/changelog): what's new in each version
- [Privacy Policy](https://musicmcp.app/privacy): the app collects no data

## Publisher

Coolplay GmbH, Vienna, Austria. Support: support@coolplay.io