Skip to main content
Glama

🎡 Spotify for Codex

Ask Codex to play music, find old favourites, build playlists, or plan a DJ set.

Python 3.11+ MIT License Spotify MCP

Get started Β· See what you can ask Β· Setup guide

NOTE

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-bundle

The 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_id

The 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 episodes

The 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 setup

Configure 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-mcp

The 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

The source uses the MIT License. Spotify AB owns the Spotify trademark and does not sponsor or endorse this project.

Available Tools

53 tools
spotify_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 AlbumsA
Read-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 AlbumsA
DestructiveIdempotent

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 AlbumsA
Idempotent

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 AlbumsA
Read-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 TracksA
Read-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 AnalysisA
Read-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 AnalysisA
Read-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 FeaturesA
Read-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 DevicesA
Read-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 PlaylistA
Read-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_planA
Idempotent

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 SongsA
Read-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 SongsA
DestructiveIdempotent

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 TracksA
Idempotent

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 PlayingA
Read-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 SpotifyA
Idempotent

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 PlaylistA
Read-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 ItemsA
Read-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 ItemsA
DestructiveIdempotent

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 PlaylistsA
Read-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 BPMB
Destructive

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 PlaylistA
DestructiveIdempotent

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 PlaylistA
Idempotent

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 PodcastsA
Read-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 EpisodeA
Read-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 ShowA
Read-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 EpisodesA
Read-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 QueueA
Read-onlyIdempotent

Return the current item and the next items in the Spotify playback queue.

Inputs: limit. Returns: queue, currently_playing

spotify_recently_playedRecently PlayedC
Read-onlyIdempotent

Return the current user's most recently played Spotify tracks.

Inputs: limit. Returns: tracks

spotify_render_resultsShow Spotify resultsA
Read-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 SpotifyA
Idempotent

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 SongsA
Read-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 AlbumsA
Read-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 EpisodesA
Read-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 ShowsA
Read-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 SongsA
Read-onlyIdempotent

Return one page of the current user's Spotify Liked Songs.

Inputs: limit, offset. Returns: total, offset, tracks, warnings

spotify_set_volumeSet Spotify VolumeB
Idempotent

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 statusA
Read-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 RecommendationsA
Read-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 ArtistsA
Read-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 TracksA
Read-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

    B3.4/5.0

    Scored across 53 tools

    Disambiguation3/5

    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.

    Naming Consistency5/5

    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.

    Tool Count1/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      -
    • F
      license
      A
      quality
      D
      maintenance
      A lightweight MCP server that enables AI assistants like Cursor and Claude to control Spotify playback, playlists, and manage tokens via OAuth.
      15
      2
      -