Spotify MCP Server
This server provides a comprehensive MCP interface for controlling Spotify playback, managing playlists and libraries, and performing advanced audio analysis for professional DJ set planning.
Playback Control: Play, pause, resume, skip tracks, adjust volume, and manage the playback queue. Get current playback state and available Spotify Connect devices.
Search & Discovery: Search for tracks, albums, artists, playlists, podcast episodes, and shows with pagination.
Playlist Management: Create, update, delete/unfollow playlists; add, remove, reorder tracks; retrieve playlist details and tracks.
Library & History: Save or remove albums/tracks; check saved albums; get recently played tracks, saved tracks, top tracks/artists (over different time ranges), and the playback queue.
Audio Analysis: Obtain detailed audio features (BPM, key, energy, danceability, etc.) for up to 100 tracks from multiple providers (Spotify, SoundNet, ReccoBeats) with field-level provenance. Compare analyses across providers to detect conflicts and tempo ambiguities.
DJ Set Planning: Audit playlists for data coverage, duplicates, tempo issues, and provider conflicts; analyze playlists to extract snapshot-bound BPM, Camelot key, and relative energy; generate optimized set orders using harmonic mixing, energy curve shaping, artist spacing, and user-defined constraints; apply, dry-run, or restore set plans with snapshot verification and rollback support.
Controls Spotify playback, searches music, manages playlists and albums, and plans DJ sets using BPM, key, and energy data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Spotify MCP Server Reorder my house playlist into a set that warms up, peaks, then cools down"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-serverThen 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 authThen 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:
analyzeDjPlaylistreads BPM, Camelot key, and playlist-relative energy, naming the source behind every value.planDjSetcreates a reviewable set order with harmonic mixing, a shaped energy curve, artist spacing, and anchors you pin by hand.applyDjSetPlanwrites 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 |
Spotify app, credentials, OAuth, connecting a client | |
Read, playback, playlist, and album tools with parameters | |
Where BPM and key come from, the analyze/plan/apply flow, set shaping, restore | |
The bundled skills and how to use them outside this repo | |
Shipping the server and skills as a plugin that tracks | |
Scripts, layout, the Spotify API rules, local data |
Available Tools
37 toolsaddToQueueB
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
applyDjSetPlanADestructive
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
auditDjPlaylistARead-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).
compareTrackAnalysisARead-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.
getTrackAudioFeaturesARead-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.
planDjSetAIdempotent
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.
sortPlaylistByBpmADestructive
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
Scored across 37 tools
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.
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.
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.
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
Spotify: Spotify Data API for Millions of songs & podcasts, artists, albums, playlists and more.
Full Spotify Web API coverage - albums, artists, playlists, player controls, and more.
Spotify MCP server for ChatGPT, Claude and any AI agent: search songs and artists, list playlists, read playlist songs, create playlist, add songs to playlist, remove songs from playlist, set playlist public or private and save to Liked Songs in your own Spotify account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Spotify yourself; Cotlet does not store your password and you need no Spotify API key. About the official Spotify API: Spotify has a full Web API and, since 23 Apr 2026, an official connector for Claude (checked 5 Nov 2026). The API needs an app you register, and in development mode the app owner must have Premium and the app allows 5 users; unlimited users need a registered business with at least 250,000 monthly users. Setup and FAQ: https://cotlet.dev/integrations/spotify-api-mcp-server
Make full songs with vocals, split stems, transcribe and analyze audio from your AI assistant.
Related MCP Servers
- FlicenseBqualityDmaintenanceEnables AI assistants to control Spotify playback, search for music, manage playlists, and interact with your Spotify library through natural language commands.19-
- FlicenseAqualityDmaintenanceEnables AI assistants to control Spotify playback, search for music, manage playlists, and access library information through the Spotify API. Requires Spotify Premium for playback control features.4-
- AlicenseBqualityDmaintenanceEnables AI assistants to control Spotify playback, manage playlists, search music, and access listening history. Requires Spotify Premium and uses secure OAuth 2.0 with PKCE authentication.13MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to control Spotify playback, search music, manage playlists and library, and access user listening insights via the Spotify Web API.-