Skip to main content
Glama
spotify-mcp

spotify-mcp

by seenws

An MCP server that lets MCP clients build and edit Spotify playlists from a description. "Moody 90s trip-hop for a rainy commute", "add three more like the last one", "drop anything over five minutes", etc. This is just a personal project intended for personal use, if you find it useful, that's a side effect, and you're welcome to use it.

How it works

Spotify deprecated /recommendations, /audio-features, /audio-analysis and related-artists for every app created after 2024-11-27, they return 403 and have no replacement. So the model itself is the recommendation engine. These seven tools give it the three things it can't do itself:

Tool

Purpose

Resolve

search_tracks

Turn "Massive Attack – Teardrop" into a track URI. Supports artist:, year:1990-1999, genre:, album:

Ground

get_my_taste

Your real top tracks/artists, so "music like I listen to" means something

Read

list_my_playlists, get_playlist

Find a playlist by name; see what's in it before editing

Write

create_playlist, add_tracks, remove_tracks

Build and edit. Batched past Spotify's 100-track-per-request cap automatically

There's a similar project named spotify-mcp-server by Marcel Marais that exposes many more functionalities. If you want to use this tool but find that the current list of exposed functions aren't enough for what you want to do, I'd recommend looking at his MCP server instead.

Related MCP server: playlist-agent

Setup

1. Create a Spotify app

At developer.spotify.com/dashboard → Create app.

Footgun 1 — the redirect URI. Spotify rejects localhost. Register the IP literal, exactly: http://127.0.0.1:8888/callback

Footgun 2 — the allowlist. New apps are in development mode: capped at 5 users, and each one must be added under Settings → User Management by their Spotify account email — including your own. Miss this and every API call 403s despite a perfectly valid token. (Extended quota has been organizations-only since 2025-05-15 and requires 250k+ monthly actives, so 5 users is the practical ceiling.)

Copy the Client ID and Client secret.

2. Build and log in

npm install && npm run build

export SPOTIFY_CLIENT_ID=...
export SPOTIFY_CLIENT_SECRET=...
npm run login

npm run login prints an authorization URL (and tries to open your browser), catches the callback on 127.0.0.1:8888, and writes a refresh token to ~/.config/spotify-mcp/token.json with mode 0600. One time only — the server refreshes access tokens itself from then on.

Scopes requested: playlist-modify-public, playlist-modify-private, playlist-read-private, playlist-read-collaborative, user-top-read. No playback scopes — this server doesn't control playback.

3. Register with your MCP client

claude mcp add spotify \
  --env SPOTIFY_CLIENT_ID=... \
  --env SPOTIFY_CLIENT_SECRET=... \
  -- node /absolute/path/to/spotify-mcp/dist/index.js

Or in a client config file:

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/absolute/path/to/spotify-mcp/dist/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "...",
        "SPOTIFY_CLIENT_SECRET": "..."
      }
    }
  }
}

Then just ask: "Make me a 20-track playlist of moody 90s trip-hop for a rainy commute."

Development

npm test     # node:test, no framework — chunking, pagination, token refresh, error handling
npm run build
npx @modelcontextprotocol/inspector node dist/index.js   # poke the tools by hand

Set SPOTIFY_MCP_TOKEN_FILE to override the token location.

Stack: @modelcontextprotocol/server v2 + zod. Everything else is a Node built-in — no express, no axios, no dotenv, no Spotify client library.

Notes

  • Auth flow: authorization code with client secret, not PKCE. Spotify doesn't rotate refresh tokens on this flow, so there's no lose-the-write-lose-the-account failure mode. Everything stays on loopback.

  • The playlist endpoints moved. Separately from the 2024-11-27 cull, Spotify retired the /tracks playlist surface in favour of /items. Unlike the cull these do have replacements, and the server uses them. Everything below 403s on the left, works on the right: GET/POST/DELETE /playlists/{id}/tracks → .../items; POST /users/{id}/playlists → POST /me/playlists; item.track on a playlist entry → item.item; playlist.tracks.total in /me/playlists → playlist.items.total; and the DELETE body key {"tracks": [...]} → {"items": [...]}. That last one isn't in Spotify's changelog — it 403s as "Insufficient client scope", which sends you hunting for a scope problem you don't have.

  • /me/playlists lies about being empty. It returns a valid, empty page roughly 40% of the time on an account that demonstrably has playlists. An empty list is a silently wrong answer rather than an error, so list_my_playlists retries up to four times before believing it. Its items.total count also lags behind writes by a few seconds; the playlist itself is correct.

  • Playlist visibility is not settable. public is accepted at creation and on update, returns 200, and is then ignored — new playlists come back public regardless. Flip it in the Spotify client. Nothing to fix here; the API just doesn't honour the field.

  • Not included: playback control, playlist rename/reorder, saved-library reads. Add when wanted.

Available Tools

7 tools
add_tracksAdd tracks to a playlistA

Append tracks to a playlist (or insert at a position). Pass as many URIs as you like — they are batched automatically. Get URIs from search_tracks; do not invent them.

Inputs: uris (required), playlist_id (required), position.

create_playlistCreate a playlistA

Create a new empty playlist, then fill it with add_tracks. Give it a name and a short description that reflects what the user asked for. Returns the playlist ID and its URL.

Inputs: name (required), public, description.

get_my_tasteGet my top tracks or artistsA

The user's actual listening history — the best available signal for what they like. Read this before building a playlist described in terms of the user's own taste ("music like what I listen to", "more of this vibe"), then choose similar music yourself. Spotify's recommendation and audio-feature endpoints no longer exist for this app. Pick the music yourself from your own knowledge, then use search_tracks to resolve each pick to a URI. Use get_my_taste to ground picks in what this user actually listens to.

Inputs: type, limit, time_range.

get_playlistGet playlist contentsA

Full track listing of a playlist, with each track's URI and its 0-based position. Read this before editing so you know what is already there — it prevents duplicate adds and lets you remove exactly the right tracks.

Inputs: playlist_id (required).

list_my_playlistsList my playlistsA

The user's playlists, with IDs. Use this to find an existing playlist to edit when the user names one ("add these to my Focus playlist") instead of creating a new one.

Inputs: no named parameters.

remove_tracksRemove tracks from a playlistA

Remove every occurrence of the given tracks from a playlist. Batched automatically. Call get_playlist first to confirm the exact URIs present.

Inputs: uris (required), playlist_id (required).

search_tracksSearch tracksA

Find tracks on Spotify and get their URIs. This is how you turn an artist/title you have in mind into something you can add to a playlist. Supports Spotify query syntax: artist:Portishead, year:1990-1999, genre:trip-hop, album:Dummy, and quoted phrases. Search one track at a time for precision. Spotify's recommendation and audio-feature endpoints no longer exist for this app. Pick the music yourself from your own knowledge, then use search_tracks to resolve each pick to a URI. Use get_my_taste to ground picks in what this user actually listens to.

Inputs: query (required), limit.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a clearly distinct action: searching tracks, reading listening history, listing playlists, reading a playlist's contents, creating playlists, adding tracks, and removing tracks. The descriptions further reinforce boundaries, so an agent should not confuse them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern: search_tracks, get_my_taste, list_my_playlists, get_playlist, create_playlist, add_tracks, remove_tracks. There are no mixed conventions or vague verbs.

    Tool Count5/5

    Seven tools is well-scoped for a Spotify playlist-management server. Each tool covers a necessary step in the core workflow without redundancy or bloat.

    Completeness4/5

    The playlist workflow is well covered: discover via search/taste, list/read playlists, create playlists, and add/remove tracks. Minor gaps like renaming or deleting playlists are missing, but they are not central to the apparent purpose.

    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
      B
      maintenance
      Enables MCP-compatible AI assistants to control Spotify Premium accounts by searching music, managing playback and devices, handling queues, creating and editing playlists, and browsing or modifying the library.
      MIT