mcp-spotify

MCP server for Spotify, focused on playlist building and music discovery. 19 granular tools designed for use with Claude and other LLM agents.

Prerequisites

• Python 3.14+
• uv
• A Spotify Premium account (required by Spotify for Web API access)
• A Spotify Developer application

Setup

1. Create a Spotify Developer App

1. Go to the Spotify Developer Dashboard
2. Click Create App
3. Under Which API/SDKs are you planning to use?, select Web API
4. Set the Redirect URI to http://127.0.0.1:8888/callback
5. Note your Client ID and Client Secret

2. Install

cd mcp-spotify
uv sync

3. Configure Environment Variables

Set these before running the server:

export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
export SPOTIFY_REDIRECT_URI="http://127.0.0.1:8888/callback"

4. First Run (Authentication)

uv run mcp-spotify

On first run, a browser window opens for Spotify OAuth authorization. After approving, the token is cached at ~/.spotify_mcp_cache and subsequent runs authenticate automatically.

Claude Desktop / Claude Code Configuration

Add to your MCP server config. If installed from PyPI:

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["mcp-spotify"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback"
      }
    }
  }
}

Or if running from a local clone:

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

Tools

Discovery

Library

Playlists

Personalization

time_range options: short_term (~4 weeks), medium_term (~6 months), long_term (all time).

Playback

OAuth Scopes

This server requests the minimum scopes needed:

• user-read-playback-state, user-modify-playback-state, user-read-currently-playing -- playback
• playlist-read-private, playlist-read-collaborative, playlist-modify-public, playlist-modify-private -- playlists
• user-top-read -- personalization
• user-library-read -- saved/liked tracks

Spotify Web API Restrictions

Spotify has progressively locked down its Web API since late 2024. This section documents what's affected and what it means for this project.

Removed from the Web API (November 2024)

Spotify removed or restricted these endpoints on November 27, 2024. They are permanently unavailable to new apps and Development Mode apps, regardless of quota:

Apps that had Extended Quota Mode approval before November 2024 retained access. New apps cannot get access to these endpoints.

Gated Behind Extended Quota (Effectively Inaccessible)

These endpoints exist but return 403 Forbidden in Development Mode. They require Extended Quota Mode, which as of May 2025 requires:

• A legally registered business entity (not individuals)
• 250,000+ monthly active users
• An active, launched service in key Spotify markets

This makes Extended Quota inaccessible for personal projects, hobby apps, and small tools.

February 2026 Development Mode Changes

On February 6, 2026, Spotify overhauled Development Mode itself:

• Spotify Premium required for app owners (this is now a prerequisite for all Web API access)
• 1 Client ID per developer
• Max 5 authorized users per app
• Search results capped at 10 per request (down from 50) for new apps
• Several more endpoints restricted (batch-get endpoints, browse categories, new releases, other-user profiles/playlists)

The POST /users/{user_id}/playlists endpoint was also removed in favor of POST /me/playlists (this server already uses the /me variant).

Note: Endpoint restrictions currently apply to newly created apps. Existing Dev Mode apps were temporarily exempted after community backlash, but this may change.

Not Yet Implemented

Potential tools that could be added within current Development Mode access:

Will Never Be Usable (for New Apps)

These would have been valuable for this project but are permanently out of reach:

The practical effect: playlist building relies entirely on search_tracks and the user's own listening history (get_my_top_tracks, get_my_top_artists) for discovery. Claude's own music knowledge fills the gap that the API no longer provides.

Development

uv run mcp-spotify           # Run the server
uv run pytest tests/ -v      # Run tests
uv run ruff check src/       # Lint
uv run ruff format src/      # Format
uv run pyright src/          # Type check

Pre-commit Hooks

This project uses lefthook for pre-commit checks. Install with brew install lefthook (or see other install methods), then:

lefthook install