spotify-mcp

An MCP (Model Context Protocol) server that lets an AI agent such as Claude control Spotify — playback, search, queue, library, and playlists — through the Spotify Web API. Built on spotipy.

Table of Contents

• Overview

• Features

• Available tools

• Demo

• Getting started

  • Prerequisites

  • Create a Spotify app

  • Install and register the server

  • Configuration

  • First-time authorization

• Project structure

• Development

• Troubleshooting

• Contributing

• License

Related MCP server: Spotify MCP Server

Overview

spotify-mcp exposes Spotify as a set of MCP tools so that an agent can start and control playback, search the catalog, manage the queue, curate your saved tracks, and build playlists on your behalf. It runs locally over stdio and talks to Spotify using your own developer credentials.

The server is organized into small, single-responsibility modules and authenticates lazily: it starts without contacting Spotify and only builds an authenticated client the first time a tool is actually called. A separate CLI command handles the one-time OAuth authorization, so the server itself never needs an interactive browser flow.

This is a personal, actively-maintained fork of varunneal/spotify-mcp.

Features

• Playback control: start, pause, skip, previous, seek, and set volume

• Search for tracks, albums, artists, and playlists

• Get detailed info about a track, album, artist, or playlist

• Manage the playback queue (add, get)

• Manage your library: list, save, and remove liked tracks

• Manage playlists: list, create, add/remove tracks, and delete

• Lazy authentication with a dedicated spotify-mcp-auth CLI for first-time login

Available tools

The server exposes six domain-grouped tools. Most take an action argument.

Playback and queue actions target the active Spotify device and require Premium. Search, get-info, library, and playlist management work without an open device.

Demo

Make sure to turn on audio.

Getting started

Prerequisites

• Python 3.12 or newer

• uv (recommended >= 0.54)

• A Spotify account. Spotify Premium is required for playback control (search, library, and playlist management work without Premium).

• A Spotify developer application (see below)

Create a Spotify app

1. Sign in at developer.spotify.com/dashboard and create an app.

2. Set the redirect URI to http://127.0.0.1:8888. You may choose any port, but Spotify now requires the loopback IP 127.0.0.1 for HTTP redirects — localhost is rejected as insecure.

3. Under the app's API settings, enable Web API.

4. While the app is in Development Mode, add the Spotify account you will authorize with under User Management. Accounts that are not on this list are rejected during authorization with a server_error.

5. Copy the Client ID and Client Secret.

Install and register the server

Clone the repository:

git clone https://github.com/chienchuanw/spotify-mcp.git

Register it as an MCP server in your client. For the Claude desktop app, edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%/Claude/claude_desktop_config.json

"spotify": {
  "command": "uv",
  "args": [
    "--directory",
    "/path/to/spotify-mcp",
    "run",
    "spotify-mcp"
  ],
  "env": {
    "SPOTIFY_CLIENT_ID": "YOUR_CLIENT_ID",
    "SPOTIFY_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
    "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888"
  }
}

Configuration

The server reads three variables, from the MCP client env block above or from a .env file in the project root:

Example .env:

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888

First-time authorization

Because the MCP server communicates over stdio, it cannot run the interactive OAuth flow itself. Authorize once with the bundled CLI, which opens your browser and captures the redirect on a local server:

uv --directory /path/to/spotify-mcp run spotify-mcp-auth

This caches an access/refresh token. The server then reads that cached token and refreshes it automatically. Re-run spotify-mcp-auth only if you revoke access or change scopes. If your account is not on the app's allowlist, the command prints guidance on how to fix it instead of a traceback.

Project structure

src/spotify_mcp/
  __init__.py   entry points: main() (server) and auth_main() (auth CLI)
  server.py     MCP wiring — list_tools / call_tool dispatch to the registry
  tools.py      tool schemas (Pydantic) + per-domain handlers + registry
  client.py     SpotifyClient facade over spotipy + the @validate decorator
  parsers.py    pure functions that narrow Spotify's verbose JSON
  auth.py       OAuth config, SCOPES, lazy get_client() factory, auth CLI
  errors.py     exception -> user-facing message formatting
tests/          pytest suite, mocks spotipy (no network, no credentials)
docs/           design spec, implementation plan, and session status files

Key design points:

• Lazy auth — the Spotify client is built on first use via get_client(), never at import time, so the server starts without credentials and only touches Spotify when a tool is called.

• @validate — decorates playback/queue methods to refresh the token if expired and inject a candidate device when none is active. Catalog, library, and playlist calls are intentionally undecorated because they need no device.

• Layered boundaries — server knows nothing of Spotify, tools handlers know nothing of the MCP session, and client knows nothing of MCP types. Each layer is unit-testable in isolation.

Development

Install dependencies (including the dev group) and run the test suite:

uv sync
uv run pytest

The tests mock spotipy and never touch the real Spotify API, so no credentials are needed to run them.

You can also inspect the server interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector uv --directory /path/to/spotify-mcp run spotify-mcp

Troubleshooting

• Make sure uv is up to date (>= 0.54 recommended).

• Ensure the client has execution permissions for the project: chmod -R 755 /path/to/spotify-mcp.

• Playback control requires Spotify Premium and an active device — open Spotify (desktop app, phone app, or the web player at open.spotify.com) and start playing so a device is available.

• redirect_uri: insecure during authorization means you are using localhost; switch both the dashboard and SPOTIFY_REDIRECT_URI to http://127.0.0.1:8888.

• server_error / access_denied during authorization usually means your account is not on the app's User Management allowlist while the app is in Development Mode.

• The server logs to stderr per the MCP spec. On macOS, the Claude desktop app writes these to ~/Library/Logs/Claude. See the MCP logging docs for other platforms.

Contributing

Contributions are welcome. Fork the repository, create a feature branch off dev, run the test suite (uv run pytest), and open a pull request against dev.

Deprecated Spotify recommendation endpoints are out of scope. Possible future work includes paginated search/playlist/album results and a deployment story for ephemeral (uvx) usage.

License

Released under the MIT License. This project is derived from the original spotify-mcp by Varun Srivastava, also MIT-licensed; the original copyright notice is retained in the LICENSE file.