An MCP server for surgical Spotify playlist editing. Where Spotify's built-in "generate a playlist from a vibe" tooling can't make precise edits, this exposes the Spotify Web API's granular playlist operations directly — so an LLM can search for tracks, then add, remove, and reorder them at exact positions.
The curation taste comes from the model; the precise placement comes from the API.
| Tool | What it does |
|---|---|
find_playlists(name) |
Find your own playlists by name (substring) → {name, uri, owner, tracks, public, owned} |
search_tracks(query, limit) |
Find tracks → {name, artist, album, year, uri} |
create_playlist(name, description, public) |
Create an empty playlist → {playlist_id, uri, url} |
save_playlist(uri) |
Add a playlist to your library ("Save"/follow) → {playlist_id, saved} |
get_playlist(playlist_id) |
Read full tracklist with positions (handles >100 tracks) |
add_tracks(playlist_id, uris, position?, skip_existing?) |
Append or insert at a position (auto-chunks to 100); skip_existing drops tracks already present |
remove_tracks(playlist_id, uris) |
Remove all occurrences of the given tracks |
dedupe_playlist(uri) |
Remove exact-duplicate tracks (by URI), keeping the first occurrence |
reorder_tracks(playlist_id, range_start, insert_before, range_length?) |
Move a block of tracks |
shuffle_playlist(uri, method?) |
Persist a randomized order — artist_spread (default, de-clusters) or random |
sort_playlist(uri, by?, order?) |
Persist a sort by year/artist/title, asc/desc |
URIs, open.spotify.com URLs, and bare IDs are all accepted interchangeably.
At the Spotify Developer Dashboard, create an
app and add this exact redirect URI (the loopback IP literal — Spotify rejects
localhost):
http://127.0.0.1:8888/callback
A free Spotify account works for playlist editing; the recommendation/audio-features endpoints (deprecated by Spotify in Nov 2024) are intentionally not used here.
cp .env.example .env
# edit .env with your client id/secret, then:
source .envuv sync # or: pip install -e .The first call opens a browser for OAuth consent. The refresh token is cached to
~/.spotify-mcp/token.json, so it only happens once.
Add to your Claude Desktop / Claude Code MCP config:
{
"mcpServers": {
"spotify": {
"command": "uv",
"args": ["--directory", "/Users/chris/devel/home/mcp-server-spotify", "run", "mcp-server-spotify"],
"env": {
"SPOTIPY_CLIENT_ID": "your_client_id",
"SPOTIPY_CLIENT_SECRET": "your_client_secret",
"SPOTIPY_REDIRECT_URI": "http://127.0.0.1:8888/callback"
}
}
}
}- Minimal scopes:
playlist-read-private,playlist-modify-private,playlist-modify-public. No playback, no library, no profile access — that is the entire trust surface. - Two dependencies only (
mcp,spotipy); pin them via the committeduv.lockand review diffs on update rather than auto-bumping. - Credentials live in a gitignored
.env/ Claude config; the token cache is gitignored.
uv sync # install deps (incl. dev group)
uv run ruff check . # lint
uv run ruff format . # format
uv run pytest # unit tests (acceptance auto-skipped)
uv run pytest --run-acceptance # + live API lifecycle (needs SPOTIPY_* creds)CI (GitHub Actions) runs the PR-title check, ruff lint/format, and the unit tests
on every PR; the CI Success job is the aggregate gate. Acceptance tests are not
run in CI — they require live Spotify credentials and stay local/manual.
MIT — see LICENSE.