spotify-mcp: A Model Context Protocol Server That Gives Claude Control of Spotify Playback

What spotify-mcp Connects, and Where the Seam Sits

Claude and other MCP-capable clients can reason about music but cannot press play. spotify-mcp is the bridge: a Python server that exposes Spotify operations as MCP tools so the model can call them. The README lists the surface area directly: start, pause and skip playback; search for tracks, albums, artists and playlists; fetch info about any of those four types; manage the queue; and manage, create and update playlists.

That list defines the audience. This is for someone who already runs an MCP client, has a Spotify developer account, and wants conversational control rather than a new music interface. It is not a library you import into your own application, and it is not a Spotify client with its own UI. The MCP client is the UI. The server is a thin translation layer between the model's tool calls and spotipy 2.24.0, which in turn calls the Spotify Web API. Every capability inherits Spotify's own limits, including the Premium requirement the troubleshooting section states plainly: "Ensure you have Spotify premium (needed for running developer API)."

The Redirect URI Is the Whole Architecture in One Detail

The configuration instructions are the most revealing part of the README, because they describe an OAuth flow that shapes how the server behaves in practice. You create an app on developer.spotify.com with a redirect URI of http://127.0.0.1:8080/callback. The README is explicit that the address must be http, an explicit loopback address, and either IPv4 or IPv6. That constraint comes from Spotify's redirect URI rules, not from this project.

Then comes the trade-off. Running via uvx, per the README, "will open the spotify redirect URI for every tool call." The documented workaround is to clone the repository and run it locally instead, which avoids the repeated redirect. That single sentence explains why the local install path exists at all. If you use the uvx snippet, expect a browser window each time the model invokes a tool. If that is unacceptable, you are committing to a git clone and a local path in your MCP config. Neither option is presented as better; the README just states the behaviour and the alternative.

The server emits logs to stderr, as the MCP specification requires. On macOS, Claude Desktop writes those logs to ~/Library/Logs/Claude. Elsewhere, the README points to the MCP quickstart documentation for log locations. For a server whose failure mode is often a silent authentication problem, knowing where stderr lands is the difference between a five-minute fix and an afternoon of guessing.

Two Install Paths and the Exact Config Keys

The uvx path is the shortest. Add this block to your MCP config, with the client ID, secret and redirect URI filled in:

{ "mcpServers": { "spotify": { "command": "uvx", "args": [ "--python", "3.12", "--from", "git+https://github.com/varunneal/spotify-mcp", "spotify-mcp" ], "env": { "SPOTIFY_CLIENT_ID": YOUR_CLIENT_ID, "SPOTIFY_CLIENT_SECRET": YOUR_CLIENT_SECRET, "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8080/callback" } } } }

The three environment variables are the entire configuration surface: SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET and SPOTIFY_REDIRECT_URI. There is no config file, no database, no token store mentioned in the README.

The local path starts with git clone https://github.com/varunneal/spotify-mcp.git, then a config entry that swaps uvx for uv with a --directory argument pointing at the clone, followed by run spotify-mcp. The README also tells you to run chmod -R 755 on the cloned directory to enable execution permissions. For config file locations, it gives two: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%/Claude/claude_desktop_config.json on Windows. Cursor and other MCP clients are mentioned but their paths are not listed, so you are on your own there.

For debugging, the README supplies one concrete command: npx @modelcontextprotocol/inspector uv --directory /path/to/spotify-mcp run spotify-mcp. The Inspector prints a URL you open in a browser. That is the only diagnostic tool documented, and it is worth using before you file an issue, since the README's troubleshooting section offers just three tips: update uv to >=0.54, fix permissions on a local clone, and confirm Premium.

Pagination, Tests and the Deprecated Recommendation Endpoints

The TODO section is unusually honest. It states that Spotify deprecated a set of recommendation features in November 2024, and that most new work will be "relatively minor or for the health of the project." The remaining items are tests and "adding API support for paginated search results/playlists/albums." The playlist-management item is struck through, meaning it shipped.

Those two open items matter more than their brevity suggests. No tests means no regression signal for anyone cloning and modifying the server. No pagination means search and playlist reads return whatever the API's default page size gives you, with no documented way to walk further. If your use case is "find my obscure live bootleg in a 4,000-track playlist," the tool surface described here may not reach it. The README does not claim otherwise.

The project's status is the other hard constraint. A notice dated March 2026 reads: "Inactive project. Most PRs will not be merged." The last push to the default branch is dated 2026-03-11, and no releases were retrieved. Taken together, this is a codebase you can read, fork and run, but not one where a filed bug is likely to be fixed upstream. The MIT licence is what makes that tolerable: you can fork, patch and redistribute without asking anyone.

How It Differs from a Purpose-Built Music Assistant

The obvious alternative is a native music assistant such as Spotify's own voice interface or a client with built-in natural-language search. The difference is architectural. A native assistant owns the whole stack: it decides what the model can do, and it can add capabilities without an external protocol. spotify-mcp owns nothing except the translation layer. Its capabilities are exactly the MCP tools it registers, and its reach is exactly what spotipy 2.24.0 and the Spotify Web API allow. When Spotify deprecated the recommendation endpoints, this project lost access to them along with every other API consumer; a native assistant would simply have kept the feature internal.

The second alternative is writing the integration yourself against spotipy. That gives you pagination, your own token handling, and tests that match your usage. The cost is that you rebuild the MCP tool definitions, the OAuth redirect dance, and the stderr logging behaviour that this project already ships. The README's credit line to contributors suggests the tool set has been shaped by real use, which is a modest but real head start over a blank file.

Licence, Maintenance and What a Fork Actually Costs

The MIT licence permits commercial and private use, modification and redistribution, provided the copyright notice and permission notice are retained. That is the standard MIT obligation, and this article is not legal advice; read the LICENSE file in the repository before you rely on it.

Maintenance cost is the sharper question. With the README declaring the project inactive and most PRs unmerged, the practical model is vendoring: clone it, pin it, and treat it as your code. The README's own local-install instructions already push you in that direction, since the clone path is the one that avoids the per-call redirect. Once you have a clone, the dependency you are actually maintaining is spotipy 2.24.0 and its relationship to the Spotify Web API, which changes on Spotify's schedule, not yours. The absence of tests means an API change surfaces as a broken tool call in your client rather than a failing build.

There is no deployment or publishing section in the README; the only such content is commented out, and it describes uv sync, uv build and uv publish for preparing a package. If you intend to publish your fork, those commands are a starting point, not a documented process.

Who Should Wire This In, and What to Check First

Use spotify-mcp if you run Claude Desktop, Cursor or another MCP client, you have Spotify Premium, and you want playback, search, queue and playlist operations available as tools. The setup is three environment variables and a JSON block, and the local clone path removes the most annoying behaviour, the browser redirect on every tool call.

Do not use it if you need paginated results, if you want a dependency with an active maintainer and a test suite, or if you are not on Premium. The README says Premium is needed for the developer API, so a free account will not get you far regardless of how well the server is configured.

Before committing, verify three things against your own setup. First, run the Inspector command with your clone path and confirm each tool completes without re-opening the redirect. Second, check ~/Library/Logs/Claude on macOS, or the location your platform documents, after a failed call, because stderr is where the server reports problems. Third, confirm your redirect URI string matches http://127.0.0.1:8080/callback exactly, since the README notes you may need to restart the MCP environment once or twice before it works. If the redirect behaviour in your client is intolerable, the local clone is the documented answer, and it is also the version you can patch when Spotify changes something.

Editorial conclusion

Adopt spotify-mcp if you want an MCP client to start playback, search the catalogue, and edit playlists through the Spotify Web API, and you accept that the README declares the project inactive. Skip it if you need pagination beyond the first result set, if you do not have Spotify Premium, or if you require a maintained dependency with tests. Before wiring it into a daily driver, run the MCP Inspector command against your clone to confirm every tool call completes without re-triggering the OAuth redirect, and check whether the uvx path still opens the browser on each call in your client.

Official sources

1. Issues
2. License: MIT
3. README
4. varunneal/spotify-mcp on GitHub