Spotify Model Context Protocol (MCP) Server

A robust, production-grade Model Context Protocol (MCP) server that connects Spotify playback, search, and library management directly to LLM Agents (such as Cursor, Claude Desktop, and other MCP clients).

Built in Python using FastMCP and Spotipy, this server includes connection pooling, log isolation, and a custom dual-authentication strategy to ensure long-term stability and compatibility with non-interactive agents.

Features

• Playback Control: Play tracks/albums/playlists, pause, skip, adjust volume, toggle shuffle/repeat, and transfer playback between devices.

• Search & Discovery: Search tracks, artists, albums, and playlists, and get tailored music recommendations based on genres/artists.

• Library Management: View and modify your "Liked Songs" library and create/manage playlists.

• Dual Authentication: Local web redirect or manual copy-paste fallback designed to run seamlessly through the agent interface.

• Robust Connection Handling: Connection pooling via requests.Session and thread-safe automatic token refreshing to prevent memory leaks and credentials expiration crashes.

• Log Safety: All server logs and debug outputs are isolated to stderr, leaving stdout purely for MCP protocol messages.

Related MCP server: Spotify MCP Server

Setup & Configuration

Prerequisites

• Python 3.10+

• A Spotify account (Spotify Premium is required for playback control features).

1. Register Spotify App

1. Go to the Spotify Developer Dashboard and log in.

2. Click Create App.

3. Name your app (e.g., "My MCP Spotify Server") and add a description.

4. In the Redirect URIs field, enter: http://127.0.0.1:8080/callback

5. Check the box for "Web API" under the APIs to request.

6. Click Save.

7. In the settings page of your new app, retrieve the Client ID and Client Secret.

2. Configure Environment Variables

Create a file named .env in the root of the Spotify MCP folder:

SPOTIPY_CLIENT_ID=your_spotify_client_id
SPOTIPY_CLIENT_SECRET=your_spotify_client_secret
SPOTIPY_REDIRECT_URI=http://127.0.0.1:8080/callback

Installation & Running

Ensure you have created the virtual environment and installed dependencies:

cd "Spotify MCP"
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run Server Locally

To run and inspect the server using the MCP CLI tool:

# Activate virtual environment
source .venv/bin/activate

# Start the dev inspector
mcp dev src/server.py

Client Integration

Add the server to your MCP client configuration (e.g., Cursor, Claude Desktop, or custom MCP client).

For example, in claude_desktop_config.json:

{
  "mcpServers": {
    "spotify": {
      "command": "/root/Spotify MCP/.venv/bin/python",
      "args": [
        "-m",
        "src.server"
      ],
      "env": {
        "SPOTIPY_CLIENT_ID": "your_spotify_client_id",
        "SPOTIPY_CLIENT_SECRET": "your_spotify_client_secret",
        "SPOTIPY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
      }
    }
  }
}

Authentication Flow

Because MCP servers run in background processes without terminal input, the server supports a smooth dual-authentication flow:

Flow 1: Automated Local Redirect (Default)

When starting up, if credentials are set but not authorized:

1. The server can attempt to open a browser to log you in.

2. Once authorized, the Spotify callback redirects to http://127.0.0.1:8080/callback?code=... which is processed, and tokens are written to .spotify_token_cache in the project root.

Flow 2: Interactive LLM/Agent Authorization (Recommended fallback)

If Flow 1 is blocked or you are running the agent on a remote environment:

1. The agent will call the get_auth_url tool.

2. The agent will display the Spotify login URL to you in the chat.

3. Open the link, log in, authorize, and copy the final URL you redirect to (e.g., http://127.0.0.1:8080/callback?code=...).

4. Paste this URL back to the agent.

5. The agent calls the complete_auth(callback_url) tool.

6. The server finishes the auth flow, caches the tokens, and immediately gains access!

Available Tools

The server exposes 24 tools categorized as follows:

Project created with Gemini Antigravity, with much love. ❤️