mcp-spotify/README.md

mcp-spotify

Python MCP server exposing Spotify library and playlist management as tools for Claude.

Prerequisites

• Python 3.11+
• Spotify Developer Account with an app registered at Spotify Developer Dashboard
  • Note the Client ID and Client Secret from your app
  • Set the Redirect URI to http://localhost:8888/callback in your app settings

Setup

Step 1: Install dependencies

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

Step 2: Configure credentials

cp .env.example .env

Edit .env and fill in your Spotify credentials:

SPOTIPY_CLIENT_ID=your_client_id_here
SPOTIPY_CLIENT_SECRET=your_client_secret_here
SPOTIPY_REDIRECT_URI=http://localhost:8888/callback

Step 3: Authenticate with Spotify

Run the server once with the --auth flag to authenticate with Spotify. This will open a browser window where you authorize the app to access your Spotify account. The access token is cached locally at .cache in the project directory for subsequent runs.

python server.py --auth

You should see: Authentication successful! Token cached.

Step 4: Register with Claude Code

Add the MCP server to your Claude Code configuration by editing ~/.claude/settings.json:

{
  "mcpServers": {
    "spotify": {
      "command": "/absolute/path/to/mcp-spotify/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-spotify/server.py"],
      "env": {
        "SPOTIPY_CLIENT_ID": "your_client_id_here",
        "SPOTIPY_CLIENT_SECRET": "your_client_secret_here",
        "SPOTIPY_REDIRECT_URI": "http://localhost:8888/callback"
      }
    }
  }
}

Note: Replace the path and fill in the env values with your actual Spotify app credentials. The env block is required because Claude Code launches the server as a subprocess from a different working directory where load_dotenv() may not find your .env file.

Replace /absolute/path/to/mcp-spotify with the actual path to your project. To find it, run pwd in the project directory:

cd /path/to/mcp-spotify
pwd

Then update the paths in settings.json accordingly. On Windows, the python path is .venv\Scripts\python.exe.

Available Tools

Tool	Description
list_playlists	List the authenticated user's Spotify playlists.
get_playlist_tracks	Get all tracks in a Spotify playlist with full metadata: name, artists, album, duration, popularity, URI, and added_at.
list_saved_tracks	Get the user's liked/saved tracks from Spotify. Optional limit parameter (default 50).
search_tracks	Search Spotify for tracks. Returns track URIs that can be passed to add_tracks_to_playlist.
create_playlist	Create a new Spotify playlist for the authenticated user. Takes name, optional description, and public flag.
add_tracks_to_playlist	Add tracks to a Spotify playlist by their URIs (e.g., spotify:track:...).