Skip to main content
Glama
README.md
# mymusic-mcp

One MCP server for your music. Connect a service once, then any MCP client — Claude Desktop, Claude Code,
Gaia's Bob, … — can search your music and play it in the background. Say "drop musics" and it plays.

| Provider | Search | Library | Background playback + control |
|---|---|---|---|
| Spotify Premium | ✅ | ✅ | ✅ on any Spotify Connect device (phone/desktop app, spotifyd, speakers) |
| Spotify Free | ✅ | ✅ | ❌ Spotify allows it for Premium only — `music_play` opens the link instead |

Roadmap: YouTube and YouTube Music providers; fine-tuning the suggestion list from your own collections.

## Requirements

Node.js 24 or newer (developed on 26, see `.nvmrc`).

## Setup

```sh
npm install
npm run build
node dist/cli.js connect spotify
```

The first `connect spotify` asks for a Client ID from your own Spotify app (one time):

1. Open <https://developer.spotify.com/dashboard> and create an app.
2. Add the Redirect URI `http://127.0.0.1:10001/callback` exactly.
3. Tick **Web API**, save, copy the **Client ID**.
4. While the app is in development mode, add your Spotify account under **User Management**.

Your browser opens, you approve, and the login is stored in `~/.config/mymusic-mcp/` (files are `0600`).
It refreshes itself; you do not log in again unless you revoke access.

Port 10001 busy? `node dist/cli.js config set callback-port <port>` and change the Redirect URI to match.

## Use it from an MCP client

Claude Code:

```sh
claude mcp add mymusic -- node /absolute/path/to/mymusic-mcp/dist/cli.js serve
```

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "mymusic": { "command": "node", "args": ["/absolute/path/to/mymusic-mcp/dist/cli.js", "serve"] }
  }
}
```

If your default `node` is older than 24 (check `node -v`), put the absolute path of a newer node binary in
`command`, e.g. `~/.nvm/versions/node/v26.13.1/bin/node`.

## Background playback without opening the Spotify app

The Web API only controls a device; something has to be online to make sound. For a player with no window,
run [spotifyd](https://github.com/Spotifyd/spotifyd) (Linux, macOS, Windows) with a device name, e.g. `Gaia`,
then make it the default:

```sh
node dist/cli.js config set spotify.default-device Gaia
```

Device choice: the one you name → the active one → your default → the only one online.

## Tools

| Tool | What it does |
|---|---|
| `music_providers` | Connected services, account, plan, capabilities, default |
| `music_connect` | Start login from chat (opens the browser on this machine) |
| `music_search` | Tracks, playlists, albums, artists |
| `music_library` | Your playlists, liked songs, saved albums |
| `music_play` | No target = default playlist or Liked Songs ("drop musics"); or a uri/link/text |
| `music_control` | pause, resume, next, previous, volume, shuffle |
| `music_devices` | Devices online now |
| `music_status` | Now playing |

## Settings

```sh
node dist/cli.js status
node dist/cli.js config get
node dist/cli.js config set spotify.default-playlist spotify:playlist:<id>
node dist/cli.js config set open-links false   # never open a browser (headless machines)
node dist/cli.js disconnect spotify
```

## Development

```sh
npm run typecheck
npm test
npm run inspect   # MCP Inspector against the built server
```