Skip to main content
Glama
Spotify MCP Server

Spotify MCP Server

Works with Codex, Cursor, Claude, Cline, and other MCP clients. The repository also ships the agent skills that guide setup, playlist curation, and DJ set planning.

Started from marcelmarais/spotify-mcp-server and since rewritten from scratch. Follow this repository's setup, not upstream's. MIT licensed.

Start here

Codex

Install the plugin with two commands:

codex plugin marketplace add martin-gomola/spotify-mcp-server --ref main
codex plugin add spotify-controller@spotify-mcp-server

Then tell Codex:

Set up Spotify for me. Do the technical parts yourself and tell me only what you need from my Spotify account.

The setup skill handles the local install and authentication, asking only for the Client ID and Client Secret from your Spotify app. See the Spotify Controller guide for the two-minute walkthrough.

Other MCP clients

You need Node.js 18+, a Spotify Premium account, and a Spotify Developer app with http://127.0.0.1:8888/callback registered as a Redirect URI. Spotify's current Development Mode requires the app owner to have Premium; playback also needs Spotify open on an available device.

git clone https://github.com/martin-gomola/spotify-mcp-server.git
cd spotify-mcp-server
npm install && npm run build
cp spotify-config.example.json spotify-config.json  # add your client ID and secret
npm run auth

Then point your client at build/index.js. The setup guide has configuration for Claude Desktop, Cline, and Cursor. BPM and key need nothing extra: they come from ReccoBeats, which takes no key.

Related MCP server: Spotify MCP Server

Try asking

  • "Play Elvis's first song"

  • "Create a Taylor Swift / Slipknot fusion playlist"

  • "Copy the techno tracks from my workout playlist into my work playlist"

  • "Reorder my house playlist into a set that warms up, peaks, then cools down"

  • "What's the BPM and key of everything in this playlist?"

What it does

The server covers playback control, search, playlist and album editing, and listening history through a focused MCP toolset. See the core tool reference; audio analysis and DJ tools are documented separately under DJ sets.

Its DJ workflow goes further:

  1. analyzeDjPlaylist reads BPM, Camelot key, and playlist-relative energy, naming the source behind every value.

  2. planDjSet creates a reviewable set order with harmonic mixing, a shaped energy curve, artist spacing, and anchors you pin by hand.

  3. applyDjSetPlan writes the approved order. It defaults to a dry run, checks the playlist snapshot before and after, and keeps a receipt so a half-applied reorder rolls back.

See DJ sets for the full analyze, plan, apply, and restore flow.

Documentation

Guide

Covers

Setup

Spotify app, credentials, OAuth, connecting a client

Tools

Read, playback, playlist, and album tools with parameters

DJ sets

Where BPM and key come from, the analyze/plan/apply flow, set shaping, restore

Agent skills

The bundled skills and how to use them outside this repo

Codex plugin

Shipping the server and skills as a plugin that tracks main

Development

Scripts, layout, the Spotify API rules, local data

Available Tools

37 tools
addToQueueB

Adds a track, album, artist or playlist to the playback queue

Inputs: id, uri, type, deviceId.

addTracksToPlaylistA

Add tracks or podcast episodes to a Spotify playlist. Accepts Spotify track IDs, episode IDs, or full Spotify URIs (e.g. spotify:episode:xxx).

Inputs: trackIds (required), playlistId (required), position.

adjustVolumeA

Adjust the playback volume up or down by a relative amount. Use positive values to increase, negative to decrease. Requires Spotify Premium.

Inputs: adjustment (required), deviceId.

analyzeDjPlaylistA

Analyze a complete Spotify playlist for professional set-order planning. Returns snapshot-bound BPM, Camelot key, relative energy, provenance, confidence when available, and unresolved data without changing Spotify.

Inputs: playlistId (required), source, refreshFeatures, featureOverrides, +1 more. Returns: coverage, playlist, warnings, positions, +5 more

applyDjSetPlanA
Destructive

Dry-run, apply, or dynamically restore an immutable DJ plan with snapshot checks, durable progress receipts, ambiguous-write reconciliation, and final order verification. Dry-run is the default.

Inputs: planId (required), expectedSnapshotId (required), action, dryRun. Returns: action, planId, status, warnings, +9 more

auditDjPlaylistA
Read-onlyIdempotent

Audit a complete Spotify playlist for audio-feature coverage, duplicate recordings, tempo ambiguity, provider conflicts, and heuristic opening/peak/reset candidates without changing Spotify.

Inputs: playlistId (required), source. Returns: coverage, playlist, warnings, chapterSignals, +6 more

checkUsersSavedAlbumsA

Check if albums are saved in the user's "Your Music" library

Inputs: albumIds (required).

compareTrackAnalysisA
Read-onlyIdempotent

Compare exact Spotify track IDs across available audio-analysis providers. Reports field-level provenance, missing providers, half/double-time-aware conflicts, and provider failures without changing Spotify.

Inputs: trackIds (required), providers. Returns: tracks, warnings, requestedTrackIds, requestedProviders

createPlaylistB

Create a new playlist on Spotify

Inputs: name (required), public, description.

getAlbumsA

Get detailed information about one or more albums by their Spotify IDs

Inputs: ids, albumIds.

getAlbumTracksA

Get tracks from a specific album with pagination support

Inputs: albumId (required), limit, offset, album_id.

getAvailableDevicesB

Get information about the user's available Spotify Connect devices

Inputs: no named parameters.

getMyPlaylistsB

Get a list of the current user's playlists on Spotify

Inputs: limit.

getNowPlayingA

Get information about the currently playing track on Spotify, including device and volume info

Inputs: no named parameters.

getPlaylistA

Get details of a specific Spotify playlist including tracks count, description and owner

Inputs: playlistId (required).

getPlaylistTracksB

Get a list of tracks in a Spotify playlist

Inputs: playlistId (required), limit, offset.

getQueueA

Get a list of the currently playing track and the next items in your Spotify queue

Inputs: limit.

getRecentlyPlayedB

Get a list of recently played tracks on Spotify

Inputs: limit.

getTopArtistsA

Get the current user's top (most-played) artists over a given time range. This is the closest thing Spotify exposes to listening statistics.

Inputs: limit, timeRange.

getTopTracksA

Get the current user's top (most-played) tracks over a given time range. This is the closest thing Spotify exposes to listening statistics.

Inputs: limit, timeRange.

getTrackAudioFeaturesA
Read-onlyIdempotent

Get BPM, key, mode, energy, danceability, valence, and related audio features for 1–100 exact Spotify track IDs with field-level provenance.

Inputs: trackIds (required), source. Returns: features, warnings, missingTrackIds, requestedTrackIds

getUsersSavedTracksA

Get a list of tracks saved in the user's "Liked Songs" library

Inputs: limit, offset.

pausePlaybackA

Pause Spotify playback on the active device

Inputs: deviceId.

planDjSetA
Idempotent

Create an immutable, snapshot-bound professional DJ set-order plan balancing tempo, Camelot compatibility, energy arc, artist spacing, constraints, and data quality. Does not change Spotify.

Inputs: analysisId (required), tempo, profile, weights, +11 more. Returns: score, planId, status, profile, +15 more

playMusicA

Start playing a Spotify track, album, artist, or playlist. Pass a Spotify URI (e.g. spotify:track:xxx, spotify:album:xxx) via "uri". For albums/playlists you can also use "context_uri". Device is selected automatically, so "deviceId" and "device_id" are optional.

Inputs: id, uri, type, offset, +3 more.

removeTracksFromPlaylistB

Remove one or more tracks from a Spotify playlist (max 100 tracks per request)

Inputs: trackIds (required), playlistId (required), snapshotId.

removeUsersSavedTracksA

Remove one or more tracks from the user's "Liked Songs" library (max 40 per request)

Inputs: trackIds (required).

reorderPlaylistItemsA

Reorder a range of tracks within a Spotify playlist by moving them to a new position

Inputs: playlistId (required), rangeStart (required), insertBefore (required), snapshotId, +1 more.

resumePlaybackA

Resume Spotify playback on the active device

Inputs: deviceId.

saveOrRemoveAlbumForUserA

Save or remove albums from the user's "Your Music" library

Inputs: action (required), albumIds (required).

searchSpotifyA

Search for tracks, albums, artists, playlists, podcast episodes, or shows on Spotify. For episodes and shows, the query matches against title, description, and publisher. Use type "episode" to find individual podcast episodes by topic or guest name, and type "show" to find podcast series.

Inputs: type (required), query (required), limit, offset.

setVolumeB

Set the playback volume to a specific percentage (0-100). Requires Spotify Premium.

Inputs: volumePercent (required), deviceId.

skipToNextA

Skip to the next track in the current Spotify playback queue

Inputs: deviceId.

skipToPreviousA

Skip to the previous track in the current Spotify playback queue

Inputs: deviceId.

sortPlaylistByBpmA
Destructive

Legacy tempo/energy ordering utility. Use planDjSet for professional set planning. Dry-run is the safe default.

Inputs: playlistId (required), mode, dryRun, source, +2 more.

unfollowPlaylistA

Remove a playlist from the current user's library (unfollow). Note: Spotify does not allow permanent deletion of playlists via the API.

Inputs: playlistId (required).

updatePlaylistA

Update the details of a Spotify playlist (name, description, public/private, collaborative)

Inputs: playlistId (required), name, public, description, +1 more.

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 37 tools

    Disambiguation4/5

    Most tools target distinct resources and actions (playlists, albums, playback, search), but the DJ-analytics cluster has overlap: auditDjPlaylist and analyzeDjPlaylist are nearly identical in purpose, and sortPlaylistByBpm overlaps with planDjSet. This creates a few ambiguous boundaries.

    Naming Consistency4/5

    Names consistently use camelCase verb_noun patterns (getPlaylist, createPlaylist, addTracksToPlaylist). Minor deviations include combined actions like saveOrRemoveAlbumForUser and the use of check instead of get in checkUsersSavedAlbums, but the overall style is coherent.

    Tool Count2/5

    With 37 tools, the server is heavily over-scoped. The large number is partly justified by Spotify's breadth (playback, library, playlists, audio features), but the DJ-planning subset alone adds 7 tools, pushing the count beyond reasonable usability and causing selection overhead.

    Completeness4/5

    The surface covers core Spotify workflows: playlist CRUD, library management, playback control, search, and user statistics. Missing minor features like shuffle/repeat, user profile, or artist follow, but the available tools handle the main use cases without dead ends.

    Related MCP Connectors

    Related MCP Servers