mymusic-mcp
by Golde34
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
```