spotify-mcp

An MCP server that wraps spotipy so Claude (or any MCP client) can search Spotify and read playlists, saved tracks, artist catalogs, and discovery signals.

Built specifically as re-com's Spotify backend — read-heavy by design, not a playback-control server. It does support creating playlists and adding tracks to them (so a re-com recommendation list can become a real playlist), but there's no play/pause/queue control; look at one of the several playback-focused Spotify MCP servers already out there for that.

Tools

A real limitation, stated plainly: Spotify restricts /recommendations and artist_related_artists for API apps created after November 2024 that don't have "Extended Quota Mode" (a manual approval Spotify grants sparingly). If your app doesn't have it, get_recommendations and get_related_artists will 403 — handle_errors turns that into a clear message rather than a raw traceback, and re-com's spotify_client.py treats it as one signal being unavailable, not a fatal error. search_music, playlists, saved tracks, and artist top tracks are unaffected.

Other Claude Code projects on this machine (e.g. re-com) call these tools by spawning this server over MCP rather than talking to spotipy/Spotify themselves — this is the only place Spotify credentials live.

Setup

1. Register a Spotify app

1. Go to the Spotify Developer Dashboard, create an app.

2. Add a redirect URI matching SPOTIFY_REDIRECT_URI (default http://127.0.0.1:8888/callback — you don't need anything actually listening on that port; see step 3).

3. Note the app's Client ID and Client Secret.

2. Install dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

3. Authenticate

export SPOTIFY_CLIENT_ID="..."
export SPOTIFY_CLIENT_SECRET="..."
python scripts/setup_auth_spotify.py

This prints an authorization URL, waits for you to log in and paste back the URL you're redirected to (works fine over SSH/headless — nothing needs to bind the redirect port), and writes the resulting token to .spotify_cache (path configurable via SPOTIFY_CACHE_PATH).

.spotify_cache is equivalent to your logged-in session — never commit it or share it. It's already gitignored. Tokens refresh automatically once cached; re-run this script only if refresh itself starts failing (e.g. the app's client secret was rotated, or you revoked access from your Spotify account settings), or if SCOPE in server.py gains new permissions (delete .spotify_cache first so the auth flow re-prompts for consent — a stale cached token won't pick up new scopes on its own).

4. Add to Claude Code

claude mcp add spotify -s user \
  -e SPOTIFY_CLIENT_ID="..." \
  -e SPOTIFY_CLIENT_SECRET="..." \
  -e SPOTIFY_CACHE_PATH="$(pwd)/.spotify_cache" \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

-s user makes it available in any Claude Code session, not just this directory. Use absolute paths for the python interpreter, server.py, and SPOTIFY_CACHE_PATH since the server can be launched from any working directory.

For other MCP clients (Claude Desktop, etc.), point them at the same command and env vars using their respective config format.

Testing

The unit test suite (tests/) runs against a hand-rolled fake spotipy.Spotify client — no network access or Spotify credentials needed:

pip install -e ".[dev]"
pytest

Error handling

Tool calls translate common failure modes into clear messages instead of raw tracebacks:

• Missing/expired auth (401) → tells you to redo authenticate step.

• Restricted/forbidden (403) → tells you it's likely a Spotify API access restriction (see the recommendations/related-artists caveat above) or a missing OAuth scope.

• Rate limiting (429) → tells you to wait, including the Retry-After hint if Spotify sent one.

• Any other API or OAuth error is reported directly rather than as a raw traceback.

License

MIT — see LICENSE.