spotify-mcp
This server provides a comprehensive MCP interface for interacting with Spotify, enabling natural language control over playback, library, playlists, audio analysis, podcasts, and DJ tools.
Playback Control: Play, pause, resume, skip, adjust volume, manage queue, view now playing and queue, list and control Spotify Connect devices.
Search & Discovery: Search for tracks, albums, artists, playlists, episodes, shows; get taste-based recommendations built from top tracks, recent plays, and Liked Songs; sample Liked Songs across full history.
Library Management: View, save, remove, and check Liked Songs; manage saved albums, shows, episodes; view recently played tracks, top tracks, and top artists (short/medium/long term).
Playlist Management: Create, update, get, delete playlists; add, remove, reorder items; sort by BPM with dry-run preview and safe snapshot checks.
Audio Analysis: Fetch audio features (tempo, key, energy, danceability, etc.) via Spotify or ReccoBeats fallback; compare providers; audit coverage and conflicts.
DJ Tools: Analyze playlists for DJ suitability (coverage, duplicates, tempo ambiguity); plan optimized set orders using energy curves (warmup-build-peak-close, steady, rising, waves); apply or restore changes with dry-run preview and receipt-based undo.
Podcast Support: Discover shows and episodes; get show details, episode lists, and metadata; manage saved shows and episodes.
Status & Rendering: Check Spotify configuration and authentication; render results cards for Spotify entities.
Allows interacting with Spotify's Web API to search music, control playback via Spotify Connect, manage playlists and Liked Songs, get audio analysis, and create snapshot-safe DJ plans.
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 search for 'lofi' and play the first result"
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.
π΅ Spotify for Codex
Ask Codex to play music, find old favourites, build playlists, or plan a DJ set.
Get started Β· See what you can ask Β· Setup guide
This open-source project has no connection to Spotify AB. Use it in line with theSpotify Developer Policy.
β¨ Rich Spotify results, inside Codex
Verified tracks, albums, artists, and playlists can appear as compact cards inside Codex. Choose a Spotify Connect device, start the exact result, or open its canonical Spotify page.
A real Codex result: a 90-minute playlist created from Liked Songs, verified track by track, and returned as a playable Spotify card.
Related MCP server: MCP Spotify Server
ποΈ Your documents, private on Spotify
The optional bundle turns a document, PDF, notes, or transcript into a polished private Spotify episode. Codex plans the chapters, lets you approve the script and local preview, narrates with free local Kokoro speech from a small model of about 340 MB, uploads through Spotify's official Save to Spotify companion, and waits until Spotify reports the episode ready. No TTS API key is required.
I use it for automated morning briefings and as a travel guide. Before a trip, I turn my notes into an episode, download it, and listen offline while walking around.
make codex-install-bundleThe basic Spotify MCP and Save to Spotify keep separate authorization grants and private token stores. Generated episodes remain in a private Spotify show, and the bundle includes safe, readback-verified deletion when you no longer want one.
A real bundle result: a locally narrated Villa Ephrussi tour guide with private Spotify hosting, cover art, chapters, official source links, and completed processing.
βΆοΈ Listen to chapter 1: A Villa Between Two Seas (MP3, 1:03)
π¬ What can I ask?
Spotify MCP routes ordinary requests through compact, progressive guidance that avoids broad tool discovery. Playlist curation and Liked Songs cleanup keep dedicated workflows. Copy a prompt below. Codex reads the required pages, preserves exact recordings, and checks the result after each write.
Audit your complete Liked Songs library
Audit all my Liked Songs for exact duplicates, alternate recordings, live versions, remasters,
and unavailable tracks. Show the exact keep/remove pairs and explain the evidence, but do not
remove anything.Rediscover music buried in years of listening history
Build me a three-hour road-trip playlist from across my full Liked Songs history. Keep the mix
varied across house, funk, indie, rock, and hip-hop, shape it into chapters, and verify the final
playlist track by track.Reshape an existing playlist without losing its character
Keep every track in my Road Trip playlist, add 25 songs that fit its existing taste, then order the
whole playlist into waves with intentional energy resets. Show me the proposed arc before changing
the playlist.Plan a DJ running order
Audit my House Party playlist for duplicates, missing tempo data, and awkward transitions. Plan a
DJ order that warms up, builds, peaks late, and closes with at least three tracks between the same
artist. Create a preview. Do not apply it yet.Generate a new harmonically ordered DJ set
Analyze these tracks and queries as a new private playlist named Late Night Set: [paste candidates].
Use the transition-cost DJ strategy, show the resolved and skipped tracks with BPM and Camelot
evidence, and preview the order before creating anything on Spotify.Turn a document into a private Spotify episode
Turn this document into a private spoken-word episode I can listen to on Spotify. Use local Kokoro
speech, show me the chapter plan and preview first, then save it to my private Spotify show.You can also search music and podcasts, inspect your queue, control Spotify Connect devices, and show verified results as playable cards inside Codex.
β¨ What it can do
πΆ Control playback: resolve a precise track, album, artist, or playlist from a query, control seek, shuffle, repeat, volume, queue, and Spotify Connect devices.
πΌοΈ Act on visual results: present the final verified selection as compact, playable cards in Codex.
π§ Find music from your library: search your full Liked Songs history, including tracks you saved years ago.
π©Ί Run Library Doctor: audit exact duplicates, alternate recordings, live and remastered versions, unavailable saves, and cleanup candidates before removing anything.
π§© Build with safeguards: bundled workflows preserve Spotify track identities. They stop after an uncertain write and preview DJ reorders before they change a playlist.
ποΈ Create private spoken-word episodes: the optional bundle turns documents into polished Spotify audio with local Kokoro speech and no TTS API key. It can also list and safely delete an exact generated episode after confirmation.
After a private episode uploads, Spotify may show it as PROCESSING for several minutes while its
audio is prepared. The workflow reports that state and keeps playlist writes blocked until Spotify
returns READY; a pending state is Spotify-side processing, not a plugin failure.
You can shape a playlist around a mood or journey, then open the result in Spotify.
π Get started
You need Python 3.11+, uv, and a Spotify Web API app. The server uses your appβs Client ID. It does not need the Client Secret.
π¦ 1. Download the project
git clone https://github.com/martin-gomola/spotify-mcp.git
cd spotify-mcp
cp .env.example .envπ 2. Configure Spotify
Create an app in the Spotify Developer Dashboard, add
http://127.0.0.1:8888/callback as its Redirect URI, then put its Client ID in .env:
SPOTIFY_CLIENT_ID=your_client_idThe setup guide covers the dashboard steps and Spotify Development Mode limits.
π 3. Install for Codex
Choose the setup you want:
make codex-install # Basic Spotify MCP
make codex-install-bundle # Spotify MCP + Save to Spotify for private spoken-word episodesThe bundle installs Spotify's official Save to Spotify companion at the tested version and asks for a second, separate Spotify authorization. It needs no TTS API key: the podcast workflow offers the free local Kokoro voice engine on first use. The basic command does not install or configure the companion.
The bundle also adds safe private-episode cleanup. Ask Codex to list your Save to Spotify episodes, then choose the exact episode to delete; deletion requires confirmation and a verified readback.
Approve the Spotify page or pages that open, then start a new Codex task. Codex starts the local server when you use it, so you can close the setup terminal.
π‘οΈ Safety by default
π Spotify tokens stay outside the repository in a private local file.
ποΈ Audio analysis and the DJ fallback may send exact Spotify track IDs to ReccoBeats when Spotify lacks the required audio data.
β The server stops after a write with an uncertain outcome. It does not retry that write.
ποΈ Low-level removal tools apply changes at once and offer no undo. The library audit workflow shows exact recording IDs before removal.
β After a playlist write, the workflow fetches the playlist and compares the result. Low-level tools return Spotifyβs response without treating an ambiguous result as success.
π§Ύ DJ apply and restore start with a dry run. Each command checks the live playlist before a write.
Complete authentication once:
make setupConfigure your MCP client to launch uv run spotify-mcp serve with this repository as its working
directory. Each client uses its own configuration. This repository provides a guided installer for
Codex. For local development and verification, follow the
development guide.
The Codex plugin starts the same command over stdio through
plugins/spotify-mcp/.mcp.json. It resolves this checkout at
~/dev/spotify-mcp by default. If you keep it elsewhere, set the absolute path before starting
Codex:
export SPOTIFY_MCP_REPO=/absolute/path/to/spotify-mcpThe plugin configuration contains no Spotify credentials. Spotify MCP and Save to Spotify retain separate authorization grants and private token stores outside the repository.
π Learn more
π Security policy
The source uses the MIT License. Spotify AB owns the Spotify trademark and does not sponsor or endorse this project.
Available Tools
53 toolsspotify_add_to_queueAdd to Spotify QueueA
Add one track or podcast episode to the Spotify queue. Provide a Spotify URI or both item_type and item_id.
Inputs: uri, item_id, device_id, item_type. Returns: uri, status, device_id, operation, +2 more
spotify_adjust_volumeAdjust Spotify VolumeA
Increase or decrease Spotify playback volume relative to the selected device's current volume, clamped from 0 to 100 percent.
Inputs: adjustment (required), device_id. Returns: status, clamped, device_id, operation, +3 more
spotify_album_library_containsCheck Saved Spotify AlbumsARead-onlyIdempotent
Check whether exact Spotify album IDs are saved in the user's library.
Inputs: album_ids (required). Returns: saved, album_ids
spotify_album_library_removeRemove Saved Spotify AlbumsADestructiveIdempotent
Remove exact Spotify album IDs through the current shared library endpoint and verify the resulting state once.
Inputs: album_ids (required). Returns: status, warning, album_ids, operation, +2 more
spotify_album_library_saveSave Spotify AlbumsAIdempotent
Save exact Spotify album IDs through the current shared library endpoint and verify the resulting state once.
Inputs: album_ids (required). Returns: status, warning, album_ids, operation, +2 more
spotify_albumsGet Spotify AlbumsARead-onlyIdempotent
Return typed details for exact Spotify album IDs. Albums are fetched through the supported singular endpoint; unknown IDs are reported separately.
Inputs: album_ids (required). Returns: albums, missing_ids, requested_ids
spotify_album_tracksGet Spotify Album TracksARead-onlyIdempotent
Return one paginated page of tracks from an exact Spotify album ID.
Inputs: album_id (required), limit, offset. Returns: total, offset, tracks, album_id
spotify_audio_auditAudit Spotify Audio AnalysisARead-onlyIdempotent
Audit audio-analysis coverage and conflicts for exact Spotify track IDs without changing Spotify or treating heuristic measurements as musical quality scores.
Inputs: track_ids (required), source, overrides. Returns: Coverage and conflict summary for a requested set of recordings.
spotify_audio_compareCompare Spotify Track AnalysisARead-onlyIdempotent
Compare Spotify and ReccoBeats readings for exact track IDs. Provider failures, missing providers, missing fields, and material conflicts remain explicit.
Inputs: track_ids (required). Returns: Side-by-side provider results without fallback or hidden synthesis.
spotify_audio_featuresGet Spotify Track Audio FeaturesARead-onlyIdempotent
Get typed audio measurements for exact Spotify track IDs. Returns explicit missing tracks and fields, field-level provenance, retained conflicts, and user overrides. Auto mode falls back to ReccoBeats only when Spotify returns 403 or 404.
Inputs: track_ids (required), source, overrides. Returns: Ordered lookup result with explicit whole-track absence.
spotify_devicesSpotify DevicesARead-onlyIdempotent
List available Spotify Connect devices and their current state.
Inputs: no named parameters. Returns: devices
spotify_dj_analyzeA
Fetch current audio evidence and store a position-safe DJ analysis.
Use anchor to retain incomplete tracks in place or error to reject
incomplete analysis. Explicit legacy features override provider values.
Audio is fetched for each call; this tool does not maintain a feature cache.
Inputs: playlist_id (required), source, features, overrides, +1 more. Returns: Stored, snapshot-bound DJ analysis summary.
spotify_dj_applyC
Preview or apply a plan with snapshot checks, receipts, and fresh verification.
Inputs: plan_id (required), dry_run, expected_snapshot_id. Returns: Typed outcome of applying or restoring a DJ playlist permutation.
spotify_dj_auditAudit Spotify DJ PlaylistARead-onlyIdempotent
Audit every position in a Spotify playlist for audio-feature coverage, exact and likely duplicate recordings, tempo ambiguity, provider conflicts, and heuristic opening, peak, and reset candidates without changing Spotify.
Inputs: playlist_id (required), source, overrides. Returns: Complete read-only audit of one stable playlist snapshot.
spotify_dj_planAIdempotent
Create an immutable deterministic DJ order without changing Spotify.
Inputs: analysis_id (required), energy_curve, artist_spacing. Returns: Immutable deterministic DJ plan returned to MCP clients.
spotify_dj_restoreB
Preview or restore the exact pre-plan order recorded in a mutation receipt.
Inputs: receipt_id (required), expected_snapshot_id (required), dry_run. Returns: Typed outcome of applying or restoring a DJ playlist permutation.
spotify_library_containsCheck Spotify Liked SongsARead-onlyIdempotent
Check whether exact Spotify track IDs are in the current user's Liked Songs.
Inputs: track_ids (required). Returns: saved, track_ids
spotify_library_removeRemove Spotify Liked SongsADestructiveIdempotent
Remove exact Spotify track IDs from Liked Songs and re-read their state for verification.
Inputs: track_ids (required). Returns: status, warning, operation, track_ids, +2 more
spotify_library_saveSave Spotify TracksAIdempotent
Save exact Spotify track IDs to Liked Songs and re-read their state for verification.
Inputs: track_ids (required). Returns: status, warning, operation, track_ids, +2 more
spotify_nextNext Spotify ItemB
Skip to the next item in the Spotify playback queue.
Inputs: device_id. Returns: uri, status, device_id, operation, +2 more
spotify_now_playingNow PlayingARead-onlyIdempotent
Return the current Spotify playback item, state, device, and volume.
Inputs: no named parameters. Returns: item, device, is_playing, progress_ms, +2 more
spotify_pausePause SpotifyAIdempotent
Pause Spotify playback on a selected or active device.
Inputs: device_id. Returns: uri, status, device_id, operation, +2 more
spotify_playPlay on SpotifyA
Start a Spotify track, album, artist, or playlist on a selected or active device. Provide a Spotify URI or both item_type and item_id.
Inputs: uri, offset, item_id, device_id, +1 more. Returns: uri, status, device_id, operation, +2 more
spotify_playlistGet Spotify PlaylistARead-onlyIdempotent
Return metadata for an exact Spotify playlist ID.
Inputs: playlist_id (required). Returns: id, url, name, owner, +6 more
spotify_playlist_addAdd Spotify Playlist ItemsA
Add exact Spotify track IDs or track/episode URIs. A returned snapshot proves acceptance; a missing snapshot is reported as ambiguous and must not be retried blindly.
Inputs: playlist_id (required), item_ids_or_uris (required), position. Returns: status, position, operation, item_count, +5 more
spotify_playlist_createCreate Spotify PlaylistA
Create a Spotify playlist, then re-read its visibility once. A failed or mismatched verification is returned explicitly and is never retried blindly.
Inputs: name (required), public, description. Returns: status, warning, operation, playlist_id, +5 more
spotify_playlist_itemsGet Spotify Playlist ItemsARead-onlyIdempotent
Return one page of tracks and podcast episodes from an exact playlist ID using Spotify's current playlist-items endpoint.
Inputs: playlist_id (required), limit, offset. Returns: items, total, offset, playlist_id
spotify_playlist_removeRemove Spotify Playlist ItemsADestructiveIdempotent
Remove exact Spotify track IDs or track/episode URIs. Pass snapshot_id to target an exact playlist version. A missing returned snapshot is explicitly ambiguous.
Inputs: playlist_id (required), item_ids_or_uris (required), snapshot_id. Returns: status, position, operation, item_count, +5 more
spotify_playlist_reorderReorder Spotify Playlist ItemsA
Move a consecutive range within an exact playlist ID using the current items endpoint. A missing returned snapshot is explicitly ambiguous.
Inputs: playlist_id (required), range_start (required), insert_before (required), snapshot_id, +1 more. Returns: status, position, operation, item_count, +5 more
spotify_playlistsGet Spotify PlaylistsARead-onlyIdempotent
Return one page of the current user's Spotify playlists.
Inputs: limit, offset. Returns: total, offset, playlists
spotify_playlist_sort_by_bpmSort Spotify Playlist by BPMBDestructive
Preview or apply the compatibility BPM and energy ordering workflow. Dry-run is the default; applying uses snapshot checks, durable receipts, and fresh verification.
Inputs: playlist_id (required), mode, source, dry_run, +2 more. Returns: Typed preview or verified mutation outcome for one compatibility sort.
spotify_playlist_unfollowUnfollow Spotify PlaylistADestructiveIdempotent
Remove an exact playlist ID from the current user's library and verify that it is no longer saved. Spotify does not expose permanent playlist deletion.
Inputs: playlist_id (required). Returns: status, warning, playlist_id, spotify_url, +1 more
spotify_playlist_updateUpdate Spotify PlaylistAIdempotent
Update metadata for an exact playlist ID and re-read each requested field once for verification.
Inputs: playlist_id (required), name, public, description, +1 more. Returns: status, warning, observed, mismatches, +3 more
spotify_podcast_discoverDiscover Spotify PodcastsARead-onlyIdempotent
Search Spotify shows and podcast episodes together, returning at most 10 typed results of each kind with canonical Spotify links.
Inputs: query (required), limit, offset. Returns: query, shows, offset, episodes, +2 more
spotify_podcast_episodeGet Spotify Podcast EpisodeARead-onlyIdempotent
Return typed metadata for one exact Spotify episode ID. Preview URL evidence may be absent and no full audio is returned.
Inputs: episode_id (required). Returns: id, uri, name, explicit, +9 more
spotify_podcast_showGet Spotify Podcast ShowARead-onlyIdempotent
Return typed details and a canonical Spotify link for one exact show ID.
Inputs: show_id (required). Returns: id, uri, name, explicit, +9 more
spotify_podcast_show_episodesGet Spotify Podcast Show EpisodesARead-onlyIdempotent
Return one bounded page of episodes for an exact Spotify show ID.
Inputs: show_id (required), limit, offset. Returns: limit, total, offset, show_id, +3 more
spotify_previousPrevious Spotify ItemB
Skip to the previous item in Spotify playback.
Inputs: device_id. Returns: uri, status, device_id, operation, +2 more
spotify_queueSpotify QueueARead-onlyIdempotent
Return the current item and the next items in the Spotify playback queue.
Inputs: limit. Returns: queue, currently_playing
spotify_recently_playedRecently PlayedCRead-onlyIdempotent
Return the current user's most recently played Spotify tracks.
Inputs: limit. Returns: tracks
spotify_render_resultsShow Spotify resultsARead-onlyIdempotent
Render a final, display-ready list of Spotify entities. Call data tools first, then pass only the results the user should see.
Inputs: items (required), title (required). Returns: Structured content shared by the model and the optional UI.
spotify_resumeResume SpotifyAIdempotent
Resume Spotify playback on a selected or active device.
Inputs: device_id. Returns: uri, status, device_id, operation, +2 more
spotify_sample_liked_songsSample Spotify Liked SongsARead-onlyIdempotent
Return a deterministic sample spanning the full history of Liked Songs. Use it for long-term taste and rediscovery instead of reading only the newest page.
Inputs: sample_size. Returns: tracks, strategy, warnings, library_total, +4 more
spotify_saved_albumsGet Saved Spotify AlbumsARead-onlyIdempotent
Return one page of albums saved in the current user's Spotify library.
Inputs: limit, offset. Returns: total, albums, offset
spotify_saved_episodesGet Saved Spotify EpisodesARead-onlyIdempotent
Return one bounded page of episodes saved in the current user's library.
Inputs: limit, offset. Returns: items, limit, total, offset, +2 more
spotify_saved_showsGet Saved Spotify ShowsARead-onlyIdempotent
Return one bounded page of shows saved in the current user's library.
Inputs: limit, offset. Returns: items, limit, total, offset, +2 more
spotify_saved_tracksGet Spotify Liked SongsARead-onlyIdempotent
Return one page of the current user's Spotify Liked Songs.
Inputs: limit, offset. Returns: total, offset, tracks, warnings
spotify_searchSearch SpotifyARead-onlyIdempotent
Search Spotify for tracks, albums, artists, playlists, podcast episodes, or shows. Returns at most 10 typed results per call.
Inputs: query (required), item_type (required), limit, offset. Returns: type, items, query, total, +1 more
spotify_set_volumeSet Spotify VolumeBIdempotent
Set Spotify playback volume from 0 to 100 percent.
Inputs: volume_percent (required), device_id. Returns: uri, status, device_id, operation, +2 more
spotify_statusSpotify statusARead-onlyIdempotent
Check whether local Spotify configuration and authentication work.
Inputs: no named parameters. Returns: product, user_id, configured, display_name, +2 more
spotify_taste_recommendationsTaste Rediscovery RecommendationsARead-onlyIdempotent
Build deterministic local rediscovery suggestions from top tracks, recent plays, and a stratified Liked Songs sample. This is local curation, not Spotify personalization.
Inputs: limit. Returns: tracks, curation, warnings, returned_count, +5 more
spotify_top_artistsTop ArtistsARead-onlyIdempotent
Return the current user's most-played artists for a Spotify time range.
Inputs: limit, time_range. Returns: artists, time_range
spotify_top_tracksTop TracksARead-onlyIdempotent
Return the current user's most-played tracks for a Spotify time range.
Inputs: limit, time_range. Returns: tracks, time_range
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 53 tools
Most tools have clear resource+action pairs, but the audio-analysis group (compare, features, audit) and the two search tools (search, podcast_discover) have overlapping responsibilities that could cause misselection. The sampling tool for liked songs also blurs with the paginated saved_tracks tool.
All tools use a consistent lowercase snake_case verb_noun pattern with the spotify_ prefix (e.g., spotify_play, spotify_pause, spotify_playlist_create). Even the DJ and podcast subdomains follow the same convention, making naming predictable.
With 53 tools, the surface is extreme for an MCP server, even for a broad domain like Spotify. The count far exceeds the 25+ threshold and makes the set overwhelming, risking agent confusion and excessive selection overhead.
The server covers most major Spotify workflows: library management, playback control, playlists, podcast/saved episodes, and audio analysis. However, there is no direct tool for fetching a single track or artist details, leaving minor gaps in basic metadata retrieval.
Maintenance
Related MCP Connectors
Spotify MCP β Web API via client_credentials OAuth
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
The official Planning Center MCP server for interacting with your ministry's data.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA FastMCP server that exposes Spotify's catalog and user context as tools for Claude, enabling track search, audio features, artist discography, recommendations, currently playing, and playlist creation.-
- FlicenseAqualityDmaintenanceA lightweight MCP server that enables AI assistants like Cursor and Claude to control Spotify playback, playlists, and manage tokens via OAuth.152-
- AlicenseAqualityCmaintenanceMCP server to control Spotify conversationally from Claude, Cursor, and other AI clients.11382 npm2MIT
- FlicenseAqualityDmaintenanceA FastMCP server that enables searching tracks, controlling playback (play, pause, skip), and retrieving currently playing content on Spotify via PKCE authentication.9-