Skip to main content
Glama
spotify-mcp

spotify-mcp

by umsachde

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

Tool

Description

search_music(query, filter="track", limit=20)

Search Spotify. filter is track or artist.

get_playlists(limit=None)

List the current user's playlists. Omit limit to fetch all of them.

get_playlist_tracks(playlist_id, limit=None)

Get the tracks in a playlist. Local files/episodes are skipped.

get_saved_tracks(limit=None)

Get the user's saved ("Liked Songs") tracks.

get_track(track_id)

Get a single track's metadata.

get_recommendations(seed_track_id, limit=25)

Spotify's algorithmic recommendations from one seed track — the closest analog to YouTube Music's radio.

get_artist(artist_id)

Get an artist's profile.

get_artist_top_tracks(artist_id)

An artist's top tracks (Spotify caps this at ~10 — there's no full-catalog endpoint).

get_related_artists(artist_id)

Artists related to the given one.

get_recently_played(limit=50)

The user's recently played tracks.

create_playlist(name, public=False, description="")

Create a new playlist owned by the current user.

add_tracks_to_playlist(playlist_id, track_ids)

Add tracks (by ID or URI) to a playlist, chunked in batches of 100.

logout()

Delete the cached OAuth token.

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.

Related MCP server: spotify-mcp

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.

Available Tools

16 tools
add_tracks_to_playlistA

Add tracks to a playlist by Spotify track ID (or URI). Chunks in batches of 100, Spotify's per-request limit.

Inputs: track_ids (required), playlist_id (required). Returns: result

create_playlistB

Create a new playlist owned by the current user and return it (id, name, ...).

Inputs: name (required), public, description. Returns: object

get_album_tracksA

Get an album's tracks. Omit limit to fetch all of them.

Album track objects are the "simplified" shape and carry no album key of their own, so callers that need one should attach it from the album they asked for.

Inputs: album_id (required), limit. Returns: result

get_artistB

Get an artist's profile (name, genres, popularity, images).

Inputs: artist_id (required). Returns: object

get_artist_albumsA

Get an artist's albums and singles. Omit limit to fetch all of them.

This plus get_album_tracks is the only route to an artist's real catalog that survives Spotify's post-Nov-2024 restrictions: get_artist_top_tracks 403s for apps without Extended Quota Mode and caps at ~10 even when it works. Appears-on and compilation albums are excluded -- they would credit the artist for other people's records.

Inputs: artist_id (required), limit. Returns: result

get_artist_top_tracksB

Get an artist's top tracks (Spotify caps this at ~10 -- there's no "full catalog" endpoint the way YouTube Music's channel Songs tab has).

Inputs: artist_id (required). Returns: result

get_current_userA

Get the authenticated user's own profile (id, display_name, ...).

The id is the only way to tell a playlist the user owns from one they merely follow: get_playlists returns both, indistinguishable except by owner.id. That distinction is load-bearing rather than cosmetic -- Spotify 403s playlist_items on another user's playlist, so a caller that treats followed playlists as its own gets an error it cannot act on.

Inputs: no named parameters. Returns: object

get_playlistsA

List the current user's playlists. Omit limit to fetch all of them.

Inputs: limit. Returns: result

get_playlist_tracksA

Get the tracks in a playlist. Omit limit to fetch the entire playlist.

Local files and episodes (no track id) are skipped. See _track_of for the two payload shapes this has to read.

Inputs: playlist_id (required), limit. Returns: result

get_recently_playedB

Get the user's recently played tracks (each item wraps a "track" key).

Inputs: limit. Returns: result

get_recommendationsA

Get Spotify's algorithmic recommendations seeded from one track.

May 403 if this app doesn't have access to /recommendations -- Spotify restricts it for apps created after Nov 2024 without Extended Quota Mode.

Inputs: seed_track_id (required), limit. Returns: result

get_saved_tracksA

Get the current user's saved ("Liked Songs") tracks. Omit limit for all of them.

Inputs: limit. Returns: result

get_trackB

Get a single track's metadata (title, artists, album, ...).

Inputs: track_id (required). Returns: object

logoutA

Delete the cached Spotify OAuth token.

Subsequent tool calls will fail until you re-authenticate via scripts/setup_auth_spotify.py.

Inputs: no named parameters. Returns: result

search_musicC

Search Spotify. filter is "track" or "artist".

Inputs: query (required), limit, filter. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools are clearly distinct by resource (tracks, playlists, artists, albums, user). Minor overlap: get_playlist_tracks vs get_saved_tracks vs get_recently_played all return track lists, but their source contexts are clear. get_artist_top_tracks and get_artist_albums both provide artist catalog access, though descriptions clarify the distinction.

    Naming Consistency4/5

    The set predominantly follows a verb_noun pattern (get_*, create_playlist, add_tracks_to_playlist, search_music, logout). The two exceptions are search_music and logout, which are still readable and not jarring. Overall consistent and predictable.

    Tool Count4/5

    16 tools is slightly above the ideal 3-15 range but appropriate for Spotify's broad domain (search, user library, playlists, artists, albums, recommendations). Each tool covers a distinct need; no obvious redundancy.

    Completeness3/5

    The surface covers search, playlist CRUD (create, read, add tracks), saved tracks, artist/album browsing, and user info. Notable gaps: no update/delete playlist, no remove tracks from playlist, no play/control playback, no track/album search filtering beyond track/artist, and no user's top items. Core browsing is solid but lifecycle coverage is incomplete.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that enables users to control Spotify playback, search music, and manage playlists through natural conversation. It is updated for the February 2026 Spotify Web API changes and supports full playlist CRUD operations.
      6
      8
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      An MCP server that enables users to control Spotify playback, search for music, and manage playlists through MCP-compatible clients. It supports features like track recommendations and playback management using secure OAuth authentication.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An unofficial MCP server that provides access to Spotify's Web API through the Model Context Protocol, enabling AI assistants to search music, manage playlists, and control playback.
      29 npm
      9
      ISC