Spotify MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with the Spotify Web API. Enables AI assistants like Claude to search music, control playback, manage playlists, and more.

Features

• Search - Find tracks, albums, artists, playlists, shows, episodes, and audiobooks

• Playback Control - Play, pause, skip, seek, volume, shuffle, repeat, queue management

• Playlists - Create, update, add/remove/reorder tracks (auto-chunks large batches)

• Library - View and manage saved tracks, albums, shows, episodes, and audiobooks

• Browse - Get details on tracks, albums, artists, episodes, chapters — single or batch

• Podcasts & Audiobooks - Browse shows, episodes, audiobooks, and chapters

• Follow - Follow/unfollow artists, users, and playlists

• User Profile - View profile, top artists/tracks, diagnostic whoami

• Resources - Subscribable snapshots of profile, playback, queue, top items

• Prompts - Pre-baked workflows for playlist building, listening summaries, library cleanup

• Transports - stdio (default), sse, and streamable-http

• Covers all non-deprecated Spotify Web API endpoints

Related MCP server: Spotify MCP Server

Example interactions

• "What am I listening to right now?"

• "Play some Radiohead on my living room speaker."

• "Skip this track and turn the volume down to 30."

• "Build me a playlist of 25 chill tracks based on what I've been listening to this week."

• "Add the last three songs I played to my 'Focus' playlist."

• "Show me my top artists from the last six months."

• "Search for live albums by Nils Frahm and save the best one to my library."

• "Unfollow every playlist I haven't opened that wasn't made by me."

• "Queue up the next episode of the show I was listening to yesterday."

Prerequisites

• uv — install with curl -LsSf https://astral.sh/uv/install.sh | sh

• A Spotify Developer account

• A Spotify app with Client ID and Client Secret

Getting Your Spotify Credentials

1. Go to the Spotify Developer Dashboard

2. Click Create App

3. Fill in the app details:

   • App name: Choose any name (e.g., "My MCP Server")

   • App description: Optional

   • Redirect URI: http://127.0.0.1:8888/callback

   • Which API/SDKs are you planning to use?: Select Web API

4. Click Save

5. On your app's page, find your Client ID

6. Click Show client secret to reveal your Client Secret

Important: The redirect URI must exactly match http://127.0.0.1:8888/callback (or whatever you set in SPOTIFY_REDIRECT_URI). Do not use localhost — use 127.0.0.1.

Installation

Pick your client below. All examples use uvx to fetch the server on demand — no clone, no manual install.

Claude Code

claude mcp add spotify \
  -e SPOTIFY_CLIENT_ID=your_client_id \
  -e SPOTIFY_CLIENT_SECRET=your_client_secret \
  -- uvx mcp-server-spotify

Other MCP clients

Most MCP clients configure servers via a JSON file. Add this entry to your client's MCP config:

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["mcp-server-spotify"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Running from a local checkout

For development, or if you want to run a modified copy:

git clone https://github.com/llyfn/spotify-mcp.git
cd spotify-mcp && uv sync

Then point your client at the local checkout instead of uvx:

"command": "uv",
"args": ["--directory", "/absolute/path/to/spotify-mcp", "run", "mcp-server-spotify"]

Configuration

Authentication

The server uses Spotify's Authorization Code flow:

1. On first use, the server opens your browser to Spotify's login page

2. Spotify will ask you to approve access — the server requests all scopes needed for the full tool set (playback, library, playlists, and user data)

3. After you authorize, Spotify redirects to the local callback server

4. The server exchanges the authorization code for access/refresh tokens

5. Tokens are stored securely in ~/.spotify-mcp/credentials.json

6. Tokens are automatically refreshed when they expire

If running in a headless environment (SSH, Docker), the auth URL will be printed to stderr — copy and paste it into a browser manually.

Re-authenticating

To re-authenticate (e.g., after revoking access), delete the stored credentials:

rm ~/.spotify-mcp/credentials.json

Available Tools

Search

Albums

Artists

Tracks

Playlists

Library

Player

Shows & Podcasts

Audiobooks

Follow

Users

Resources

Snapshots of user state exposed under the spotify:// URI scheme. MCP clients can include them as context or subscribe for updates without calling a tool.

Prompts

Canned workflows MCP clients can offer in their prompt picker. Each one walks the assistant through a multi-step task using the tools above.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT - see LICENSE for details.