Spotify MCP Server

A Python-based Model Context Protocol (MCP) server that connects your AI assistant (Claude Desktop, Cursor, etc.) directly to the Spotify Web API. This allows the AI to inspect your current playback state, search for music, trigger recommendations, and control your player (play, pause, skip, adjust volume, queue tracks).

Built using Python 3.12+, the official FastMCP SDK, uv for dependency/project management, and fully type-annotated with strict mypy validation.

---

Features

🛠️ Exposed Tools

• get_current_playback: Retrieves details about your active device, current volume, track name, artist, album, and progress.
• pause_playback / resume_playback: Pauses or resumes playback.
• skip_next / skip_previous: Skips to the next or previous track.
• set_volume: Adjusts player volume (0 to 100).
• add_to_queue: Appends a specific track URI to the queue.
• search_spotify: Searches for tracks, albums, artists, or playlists.
• play_by_search: Searches for an item and immediately starts playing the top result.
• get_recommendations: Fetches track recommendations based on seed genres (e.g. lofi,chill).

📊 Exposed Resources

• spotify://status: Exposes the text description of the currently playing track.

💬 Exposed Prompts

• vibe_check: Guides the AI to curate and play a playlist matching your current coding task, energy level, and mood.

---

Prerequisites

1. Spotify Premium: The Spotify Web API Player endpoints require a Spotify Premium subscription to accept control commands.
2. uv Package Manager: Install uv if you haven't already:

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

---

Setup & Installation

1. Register a Spotify Developer App

1. Go to the Spotify Developer Dashboard and log in.
2. Click Create App and fill in the details:
   • App name: E.g. My Local MCP Server
   • Redirect URI: http://127.0.0.1:8888/callback (Crucial for the authentication script to run successfully)
3. Under the app settings, copy your Client ID and Client Secret.

2. Configure Environment Secrets

Create a .env file in the root of this project:

cp .env.example .env

Open .env and fill in your client keys:

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_PORT=8888

3. Generate Spotify Refresh Token

Run the built-in OAuth helper script:

uv run get_token.py

• This script spins up a temporary web server on 127.0.0.1:8888 and opens your default web browser to authorize the required permissions (user-read-playback-state, user-modify-playback-state, user-read-currently-playing).
• After clicking "Agree", you will see a success message. Return to the terminal and copy the printed SPOTIFY_REFRESH_TOKEN to your .env file:

SPOTIFY_REFRESH_TOKEN=your_generated_refresh_token_here

---

Development & Type Checking

Ensure the codebase is type-safe and conforms to the static analysis rules:

uv run mypy .

---

MCP Client Configuration

To register this server with your AI client, add the following configuration block:

Claude Desktop

Add this to your claude_desktop_config.json (usually located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS).

Option A: Hiding Your Absolute Path (Recommended)

To keep your personal home directory paths private and avoid exposing them in configuration files, you can use an environment variable (e.g., SPOTIFY_MCP_DIR).

1. Export the variable in your shell profile (e.g., ~/.zshrc or ~/.bash_profile):

   export SPOTIFY_MCP_DIR="/path/to/spotify-mcp-server"

2. Configure Claude Desktop to execute uv via a login shell, which resolves the environment variable dynamically:

   {
     "mcpServers": {
       "spotify": {
         "command": "zsh",
         "args": [
           "-l",
           "-c",
           "uv --directory \"$SPOTIFY_MCP_DIR\" run main.py"
         ]
       }
     }
   }

   (If you are using bash, replace "command": "zsh" with "command": "bash" and load profile accordingly)

Option B: Standard Direct Configuration

If you do not mind exposing your directory path, configure the absolute path directly:

{
  "mcpServers": {
    "spotify": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spotify-mcp-server",
        "run",
        "main.py"
      ]
    }
  }
}

(Note: Replace /path/to/spotify-mcp-server with the actual absolute path to this repository on your system)