@novalux12/spotify-mcp
Installed, started with no arguments, no environment and no input, and listed its tools. Run 2026-11-16.
Needs to start: nothing
Returns a result when called with no setup: 1 of 5 tools tried
Contacts while installing and starting: nothing
What it contacted
Nothing besides the npm registry it was installed from. Watched from outside its sandbox while it was installed and started with no input. Its tools may still contact things when called.
Starting it
npx -y @novalux12/spotify-mcp@3.1.1
Installing a package runs its code. Use a sandbox for anything you have not read.
Calling its tools
5 tools that take no input and look read-only were called once with nothing. 1 returned a result.
get_saved_tracks | No usable answer tool reported an error: get_saved_tracks could not authenticate with Spotify; run "spotify-mcp auth" and retry. |
get_saved_albums | No usable answer tool reported an error: get_saved_albums could not authenticate with Spotify; run "spotify-mcp auth" and retry. |
get_saved_shows | No usable answer tool reported an error: get_saved_shows could not authenticate with Spotify; run "spotify-mcp auth" and retry. |
get_saved_episodes | No usable answer tool reported an error: get_saved_episodes could not authenticate with Spotify; run "spotify-mcp auth" and retry. |
get_saved_counts | Returned a result 0.6 s · 1,202 characters |
During the calls it contacted nothing it had not already contacted.
Only tools whose names read like looking something up, with no required input, are tried, five at most. Tools that need input, and anything that sounds like it changes or sends something, are not called.
What its tools tell an agent
In the tool descriptions, nothing that talks about the user, other tools or private files, or uses hidden characters.
Found by simple pattern rules in each tool's description (up to 3,000 characters), quoted as written. Parameter descriptions are not scanned. A clean result is not a safety review.
Tools
search query, types, limit, offset, include_external, market, response_format, max_results
Search Spotify's catalog for tracks, artists, albums, playlists, shows, episodes, or audiobooks. Pass `types` as an array (e.g. `["artist"]`) to search a single kind — no track/album fallback noise. Decision guide: search (general, ≤10/type), search_deep (paginated fetch_all up to 50/type), search_fresh (tag:new last 2 weeks), search_by_isrc (exact ISRC), whats_new (personal radar from follows).
get_saved_tracks limit, offset, market, fetch_all, response_format, max_results
Get tracks saved in the user's Liked Songs. Set fetch_all=true to retrieve the entire collection. Output is capped by max_results (default: SPOTIFY_MCP_MAX_ITEMS).
get_saved_albums limit, offset, market, fetch_all, response_format, max_results
Get albums saved in the user's library. Set fetch_all=true to retrieve the entire collection. Output is capped by max_results (default: SPOTIFY_MCP_MAX_ITEMS).
get_saved_shows limit, offset, fetch_all, response_format, max_results
Get podcast shows saved in the user's library. Set fetch_all=true to retrieve the entire collection. Output is capped by max_results (default: SPOTIFY_MCP_MAX_ITEMS).
get_saved_episodes limit, offset, market, fetch_all, response_format, max_results
Get podcast episodes saved in the user's library. Set fetch_all=true to retrieve the entire collection. Output is capped by max_results (default: SPOTIFY_MCP_MAX_ITEMS).
126 more tools
save_to_library uris, dry_run, response_format
Preferred. Accepts the widest URI mix (track, album, episode, show, audiobook, user, playlist) in one request. Save one or more items to the user's library via Spotify's unified library endpoint. Max 40. PREVIEWS BY DEFAULT — pass dry_run=false to commit.
remove_from_library uris, dry_run, response_format
Preferred. Accepts the widest URI mix (track, album, episode, show, audiobook, user, playlist) in one request. Remove one or more items from the user's library via Spotify's unified library endpoint. Max 40. PREVIEWS BY DEFAULT — pass dry_run=false to commit. Removals of 10+ items additionally require elicitation confirmation (or SPOTIFY_MCP_CONFIRM=never for automation).
get_saved_counts response_format
Library size snapshot: counts for tracks/albums/shows/episodes/audiobooks/playlists via limit=1 reads — no item paging. The total covers library saves only: playlists are owned and followed collections, so their count is reported alongside the library rows and excluded from the total. A collection that could not be read (rate limited, gated, or erroring) is reported as unreadable with its reason and left out of the total — it is never reported as 0. One attempt per collection: a rate limit is surfaced, not retried. Quota: 6 GETs.
search_saved_albums query, artist, added_after, max_results, scan_cap, response_format
Search saved albums (client-side filter over bounded walk). Quota: GET /me/albums paged.
search_saved_shows query, max_results, scan_cap, response_format
Search saved podcast shows (bounded walk + client-side filter). Quota: GET /me/shows paged.
search_saved_episodes query, show, max_results, scan_cap, response_format
Search saved episodes (bounded walk + client-side filter). Quota: GET /me/episodes paged.
search_saved_audiobooks query, max_results, scan_cap, response_format
Search saved audiobooks (bounded walk + client-side filter). Quota: GET /me/audiobooks paged.
check_in_library uris, response_format, max_results
Preferred. Accepts the widest URI mix (track, album, episode, show, audiobook, artist, user, playlist) in one request. Check whether items are saved in or followed by the user — this tests LIBRARY-SAVED/FOLLOWED state, distinct from check_following_artists which only tests artist FOLLOW state. Returns a boolean per URI via Spotify's unified endpoint. Max 40. Following an artist is no longer expressible: Spotify's February 2026 changes removed PUT/DELETE /me/following, and this endpoint's save side does not accept spotify:artist: URIs, so there is no endpoint that can follow or unfollow an artist. This read still answers the question for artist URIs.
search_saved_tracks query, artist, album, added_after, added_before, sort_by, limit, max_items, response_format, max_results
Search your Liked Songs (saved tracks) by text query and optional facets — client-side filter over a bounded walk of /me/tracks. For catalog-wide search use search. Reports walk truncation.
get_now_playing market, additional_types, response_format
Full device/session state for what is playing right now — item, progress, plus shuffle/repeat mode, active device, and volume. For a lightweight item+progress poll use get_currently_playing instead.
get_currently_playing market, additional_types, response_format
Lightweight poll of what is playing right now: the item and progress only. For full session state (shuffle/repeat mode, active device, volume) use get_now_playing instead.
play_from_search query, search_type, device_id, market, response_format, dry_run
Search Spotify by name and immediately play the best match. Works for songs and podcast episodes — no URI needed.
play context_uri, uris, offset, offset_uri, position_ms, device_id, response_format, dry_run
Start or resume playback. Optionally target specific content.
pause device_id, response_format, dry_run
Pause playback on the active device
skip_next device_id, response_format, dry_run
Skip to the next track in the queue or context.
skip_previous device_id, response_format, dry_run
Skip to the previous track. If more than 3 seconds in, restarts the current track first.
seek position_ms, device_id, response_format, dry_run
Seek to a position in the current track
set_volume op, volume_percent, delta_step, device_id, device_ids, all_devices, exclude_device_id, response_format, dry_run
Set playback volume on one device, on a selection of devices, or across every live device. `volume_percent` sets an absolute level; `delta_step` nudges the current level by a signed step. `op` picks the variant: "mute" drops to 0 and remembers the level, "unmute" restores what mute remembered, "preset" applies the per-device presets stored by set_device_volume_preset, and "level" with no volume_percent copies the active device's level to the others. Quota: 1 write for a single device; 1 read + N writes when fanning out.
set_shuffle state, device_id, response_format, dry_run
Enable or disable shuffle mode
set_repeat state, device_id, response_format, dry_run
Set repeat mode: off, context (repeat playlist/album), or track (repeat single track)
get_queue response_format, max_results, view, include
Read the playback queue. Use this for queue CONTENTS (what is playing, what is up next, how long it runs, what repeats). Use peek_next for a short lookahead. Quota: 1 read; view=enriched and include=runtime add one GET /me/player, and the context label adds one catalog read.
add_to_queue uri, device_id, response_format, dry_run
Add a track or episode to the end of the playback queue.
get_devices response_format, max_results
List available Spotify Connect devices. The same rows are readable as a resource with no tool call at spotify://player/devices ('?format=json' returns the raw API object).transfer_playback device, play, preserve_position, restore_shuffle_repeat, volume, device_id, response_format, dry_run
Move playback to a different Spotify Connect device, named by exact id, by the label you gave it, or by a case-insensitive name substring. A plain transfer restarts the track at 0:00 on the target; `preserve_position: true` carries the current track and play position across instead, and `restore_shuffle_repeat: true` re-applies the current shuffle and repeat modes on the target. Quota: 1 read to resolve the device, then 1–4 writes depending on the flags.
get_followed_artists limit, after, fetch_all, response_format, max_results
Get the artists the user follows. fetch_all=true walks every page; limit/after page manually.
check_following_artists ids, response_format, max_results
Check if the user follows specific artists — this tests FOLLOW state, not library-saved state (for that use check_in_library). Accepts IDs or spotify:artist: URIs. Rows carry {id, uri, follows}; returns a boolean per ID. Max 50.following_analytics group_by, top_n, response_format, max_results
Followed-artist rollups from the tag sidecar; popularity/followers unavailable (Spotify no longer returns those fields). Quota: GET /me/following.
get_user_profile user_id, response_format
Get any Spotify user's public profile (display name, profile image). Removed by Spotify's February 2026 Web API changes — unavailable for newer app registrations. The `followers` field was separately removed from user profiles, so no follower count is reported
get_user_playlists_by_id user_id, limit, offset, response_format, max_results
List another Spotify user's public playlists (paginated). Removed by Spotify's February 2026 Web API changes — unavailable for newer app registrations. Output is capped by max_results (default: SPOTIFY_MCP_MAX_ITEMS).
get_user_playlists response_format, max_results, limit, offset, fetch_all
List the current user's playlists
get_playlist response_format, max_results, playlist_id, id, limit, offset, market, fields, additional_types, fetch_all
Get a playlist's metadata (including cover image) and items. Use market to relink tracks and flag unavailable ones, and fields/additional_types to trim the payload — both are forwarded to the metadata read and the item pages.
get_playlist_items response_format, max_results, playlist_id, id, limit, offset, market, fields, additional_types, fetch_all
List a playlist's items on a single page. Use market to relink tracks and flag unavailable ones, and fields/additional_types to trim the payload.
get_playlist_cover response_format, max_results, playlist_id, id
Get a playlist's cover image URLs
upload_playlist_cover playlist_id, jpeg_base64, dry_run
Replace a playlist's cover image with a base64-encoded JPEG. Requires the ugc-image-upload scope on the Spotify developer dashboard app (plus playlist-modify-public/private); without it Spotify rejects the upload with 403.
create_playlist name, description, public, collaborative, dry_run
Create a new playlist for the current user. Set dry_run=true to preview without creating.
add_to_playlist playlist_id, uris, check_duplicates, position, dry_run
Add tracks or episodes to a playlist. Max 100 URIs per call.
remove_from_playlist playlist_id, uris, snapshot_id, dry_run
Remove tracks or episodes from a playlist. Max 100 entries per call.
update_playlist playlist_id, id, name, description, public, collaborative, dry_run
Update a playlist's name, description, or visibility
reorder_playlist_items playlist_id, range_start, range_length, insert_before, dry_run
Move a range of items within a playlist. Spotify semantics: when insert_before > range_start, the effective destination shifts down by range_length because the moved range is lifted out first (e.g. moving [2] to insert_before=4 lands it AT index 3).
replace_playlist_items playlist_id, uris, dry_run
Replace ALL items in a playlist with the supplied URIs, overwriting the current contents. Lists longer than 100 URIs are sent in chunks internally (replace + appends).
find_duplicates_in_playlist response_format, max_results, playlist_id, match_by
Find duplicate tracks in a playlist under one published matching rule. `match_by` selects the rule (`uri` — the same track object twice; `name_artist` — same name and credited artists, catching relinks and remasters; `name` — same title only) and the rule is echoed back as `match_by`, so a group count is never unattributable. See the duplicate-matching vocabulary in SPEC section 4.
remove_duplicate_playlist_items playlist_id, match_by, include_relinked, dry_run
Remove duplicate items from a playlist: keeps the first occurrence of each track and removes later repeats, under the `match_by` rule the other duplicate tools use — `uri` (default, exact repeats), `name_artist` (same name and credited artists, catching remasters and relinks under a new URI) or `name` (same title only). The rule applied is echoed as `match_by`. Supports dry_run; removals of 10+ items ask for confirmation via elicitation. See the duplicate-matching vocabulary in SPEC section 4.
clean_all_playlists match_by, include_relinked, dry_run, apply, response_format, max_results
Scan every playlist in your library for duplicate items (repeated URIs, and on opt-in same-song copies under different URIs when match_by=name_artist). Reports per-playlist findings by default; pass apply=true to remove them (keeps the first occurrence of each group). Bulk removals ask for one confirmation before anything is deleted. See the duplicate-matching vocabulary in SPEC section 4.
check_playlist_following playlists, response_format, max_results
Check if you follow 1–50 playlists. Follow state: GET /me/library/contains?uris=spotify:playlist:<id>,… (40/req, 1–2 GETs). Unreadable state reports unknown, never not-followed.
clone_playlist_cover source_playlist_id, target_playlist_id, image_index, dry_run
Copy cover image from source playlist to target. Quota: GET images + PUT images (plus image fetch).
compare_playlist_covers playlist_a, playlist_b, limit, scan_cap, response_format, max_results
Compare two playlists covers: URL equality, dimensions. Quota: 2 GETs.
get_playlist_snapshot playlist_id, response_format, max_results
Expose snapshot_id + item count for optimistic concurrency. Quota: 2 GETs.
playlist_collab_toggle playlist_id, collaborative, public, dry_run
Toggle collaborative/public flags (guards public=true && collaborative=true 400). Quota: GET + PUT.
playlist_sort playlist_id, sort_by, dry_run, response_format, max_results
Sort a playlist in place by added_at/name/artist/duration. Quota: GET all + PUT/POST. popularity is not a sort key: the API no longer returns it on playlist items.
playlist_shuffle playlist_id, seed, dry_run
Fisher-Yates shuffle a playlist (seeded optional). Quota: GET all + PUT/POST.
playlist_reverse playlist_id, dry_run
Reverse a playlist in one atomic replace. Quota: GET all + PUT/POST.
playlist_union playlists, target_playlist_id, target_name, limit, scan_cap, max_results, response_format, dedupe, dry_run
Union of 2–10 playlists into target (deduped, first-seen order). An empty union empties the target the same way subtract does. Quota: N GETs + PUT/POST; replacing an existing target also reads its current items and its playlist metadata to measure the destructive impact.
playlist_subtract base_playlist_id, playlists, limit, scan_cap, max_results, response_format, dry_run
Remove tracks of B..N from A by REWRITING A: one PUT replaces every row with the ones that survive, so any row of A absent from the union is DELETED, and the rows that remain are re-written in order. Subtracting every track empties A via one PUT with an empty uris array (Spotify's documented clear); a reply with no snapshot_id reports unconfirmed, not ok. Quota: N GETs + PUT.
playlist_symmetric_difference playlist_a, playlist_b, limit, scan_cap, response_format, max_results
Tracks in exactly one of two playlists (XOR). Quota: 2 GETs.
playlist_trim playlist_id, keep, keep_which, dry_run
Trim playlist to N items (keep first/last/random) by OVERWRITING the playlist: every row outside the kept set is DELETED, and the kept rows are re-written in the new order. An overwrite that deletes rows asks for confirmation first. Quota: 2 walks of the playlist items + 2 metadata GETs + PUT/POST.
merge_playlists playlists, target_playlist_id, new_name, public, response_format, max_results, limit, scan_cap, dry_run
Merge multiple playlists into one. Deduplicates tracks across sources (first-seen order wins) and adds them in batches of 100. Pass target_playlist_id to append to an existing playlist (it is NOT cleared) or new_name to create a fresh playlist.
diff_playlists response_format, max_results, limit, scan_cap, playlist_a, playlist_b, dry_run
Compare two playlists up to the configured source cap: tracks only in A, only in B (by track ID), and tracks present in both but at different positions. Rendered rows are capped by max_results; truncation metadata reports when source walks hit scan_cap.
overlap_playlists response_format, max_results, limit, scan_cap, playlists, min_overlap, dry_run
Find tracks shared across playlists: reports how many playlists each track appears in and lists tracks present in at least min_overlap playlists (default: all of them), most-shared first.
batch_add_to_playlist target_playlist_id, target_lane, source_uris, dedupe, dry_run, limit, scan_cap, response_format, max_results
Add tracks from multiple source URIs (tracks, albums, artists, playlists) to a target playlist in one call. Dedupes within the batch and optionally against the existing playlist. Batches writes in groups of 100. Dry-run previews without writing. Elicitation for 100+ tracks. Target the playlist by ID/URI/URL or by lane name.
copy_playlist source_playlist_id, new_name, description, public, collaborative, dry_run, limit, scan_cap, response_format, max_results
Duplicate an existing playlist into a new playlist, preserving track order. Creates the new playlist then adds tracks in batches of 100. Dry-run reports what would be created.
move_items_between_playlists source_playlist_id, source_lane, target_playlist_id, target_lane, mode, dedupe, filter, dry_run, limit, scan_cap, response_format, max_results
Bulk rehome items between playlists. Mode copy keeps the source intact; mode move removes from source after copying — by playlist position, removing exactly the transferred occurrences and leaving any other copy in the source. Supports dedupe against target and optional name/artist filter. Either side may be named by lane.
follow_playlist playlist_id, public, dry_run, response_format
Follow a playlist — save it to your Spotify library — via PUT /me/library. Spotify removed the playlist-followers endpoints in Feb 2026; this is the only way to follow a playlist. Supports dry_run (default true); writes require confirmation unless SPOTIFY_MCP_CONFIRM=never.
unfollow_playlist playlist_id, dry_run, response_format
Unfollow a playlist — remove it from your Spotify library — via DELETE /me/library. Always asks before writing unless SPOTIFY_MCP_CONFIRM=never.
pin_playlist playlist_id, public, dry_run, response_format
DEPRECATED, use follow_playlist. This tool never pinned anything; it has always saved the playlist to your Spotify library via PUT /me/library.
unpin_playlist playlist_id, dry_run, response_format
DEPRECATED, use unfollow_playlist. This tool never unpinned anything; it has always removed the playlist from your Spotify library via DELETE /me/library.
playlist_template_apply template, name, limit, public, description, dry_run, response_format
Create an instant mood/vibe playlist from a template (focus, wind-down, gym, commute) composed from your existing listening data. Creates a new playlist and fills it.
spotify_doctor verbose, response_format
Run read-only diagnostics: token presence/expiry, auth-time scopes vs write tools enabled by active toolsets, Premium gating, rate-limit cooldown, config state, visible account details when reachable, and the live registered-tool surface with toolset/scope/READONLY trim causes. The only live request is GET /me; no mutation requests are issued.
list_accounts response_format
List every local account this server can act as, and which one it is acting as now. Returns each account's account_id, profile name, display name and token file PATH — never any token material. Reads the local registry and one GET /me for the acting account; no mutation requests are issued.
switch_account profile, response_format
Change which registered account this session acts as. Takes effect for every subsequent call in this session: the client re-points its token file, drops the previous account's cached reads and validators, and refuses to switch while a request is in flight. Asks for confirmation first, because every later write then lands in the new account's library. Changes local session state and the account registry only — it issues no Spotify writes.
find_tool query, response_format, limit
Search the live tool registry by name or description substring — the fastest way to discover which of the 500+ tools handles a job. Discovery set: find_tool/inspect_tool/toolset_report are always available (also via catalog). Use this first when unsure which verb to use (e.g., playlist vs snapshot vs search).
inspect_tool tool_name, response_format
Show one tool's full description and input schema before calling it
toolset_report response_format
Report the active toolsets and registration modules, plus the live registered tool count — answers "how much surface is exposed right now". Discovery set; always available. Also see find_tool / inspect_tool.
call_tool name, arguments
Call any REGISTERED tool by name — the dispatcher that makes a trimmed surface usable. find_tool discovers a name, inspect_tool shows its schema. Reaches only tools this session registered; for anything else use enable_toolset. Refuses to call itself.
enable_toolset sets
Register an inactive toolset into THIS session and emit the MCP tools-list-changed notification — widens the surface without a restart. Takes the SPOTIFY_MCP_TOOLSETS vocabulary (all, core, playback, catalog, playlists, library, personalization, statsfm, taste, discovery, portability). Reverts entirely if it would breach the aggregate schema budget; refuses a module SPOTIFY_MCP_READONLY hides.
expand_mood_to_queries mood, max_tokens, response_format
Turn a free-text listening mood into search terms (genres, keywords, terms to avoid) for search. Uses the host model via MCP sampling when the host advertises the sampling capability; otherwise returns a built-in static map. Calls no Spotify endpoint and changes nothing. A model reply that cannot be parsed returns isError after one retry — it is never replaced by a guess.
save_discover_weekly archive_name, dry_run, response_format
Archive your Discover Weekly into a regular playlist (creates or overwrites the archive). Resolves Discover Weekly via /me/playlists exact match first, falling back to search (unverified); dry_run previews; idempotent if archive already matches. Result echoes source identity (owner, url, verified).
save_release_radar archive_name, dry_run, response_format
Archive your Release Radar into a regular playlist (creates or overwrites the archive). Resolves Release Radar via /me/playlists exact match first, falling back to search (unverified); dry_run previews; idempotent if archive already matches. Result echoes source identity (owner, url, verified).
export_library_json output_dir, format, response_format
Export your full library (saved tracks, albums, shows, episodes, audiobooks) to a local directory as JSON or CSV sidecar files. Respects SPOTIFY_MCP_FETCH_ALL_CAP per type; when capped, reports cap_reached + truncated and a prose footer ("first N of … — raise SPOTIFY_MCP_FETCH_ALL_CAP").export_followed_artists output_dir, format, response_format
Export your followed artists to a local directory as JSON or CSV. Fields: uri, name, genres. The file's exported_at is the export time, not a per-artist follow date (Spotify does not expose followed_at).
export_profile_state output_dir, include_history, response_format
Export local sidecar stores (scenes, genre-tags, playback-ext, search-history, mutations, artist-watchlist) to a single schema-versioned JSON archive. artist-watchlist is ~/.spotify-mcp/artist-watchlist.json; SPOTIFY_MCP_DATA_DIR overrides that directory.
import_profile_state input_path, mode, dry_run, response_format
Restore local sidecar stores from a profile-state archive. merge unions each store on its own keys and de-duplicates search_history by entry id; overwrite replaces each store, keeping a 0600 <file>.bak of what it replaced. The mutation ledger (stores.mutations_history) is export-only: it is never appended to or replaced, and an archive carrying it is reported as skipped. dry_run reports the per-store plan and writes nothing. Refuses newer schema versions.
export_listening_history output_dir, format, limit, max_items, before, after, response_format
Export your listening history (recently played) to a JSON or CSV sidecar by walking /me/player/recently-played with before-cursor pagination. Respects SPOTIFY_MCP_FETCH_ALL_CAP; writes file 0600 and reports path + counts.
export_all_playlists output_dir, format, include_items, scope, response_format
Export every owned (or all) playlist with metadata + items to a sidecar file. Quota: GET /me/playlists + N×GET /playlists/{id}/items; capped by fetchAllCap.library_snapshot_diff before_path, after_path, response_format
Diff two sidecar JSON files (library.json or playlists.json): added/removed counts + samples. Quota: local only (no API).
history_search query, scope, response_format
Search portability, backup and mutation-history stores; hits name their source. Quota: local only (no API).
import_from_sidecar input_path, dry_run, response_format
Additive restore from a library.json sidecar written by export_library_json: re-adds every missing saved item across all five collections (tracks, albums, shows, episodes, audiobooks) through the unified PUT /me/library endpoint, skipping items the library already holds. Rows whose uri is not a canonical spotify:<kind>:<22-char id> URI are counted as invalid and never sent. Collections the file does not carry are named in absent_keys. The exporter's own truncated / cap_reached flags are surfaced as sidecar_truncated + truncated_collections: a capped sidecar restores only the rows it holds and says so, and a file with no flag reports completeness as UNKNOWN rather than complete. The prompt and the result both state the sidecar path, the date the file itself declares (exported_at, or the named reason it declares none — never the mtime), the row count, the one use being made of it, and whether a human confirmed that use (see consent_note). dry_run=true by default. Quota: local read + contains-check + chunked writes when dry_run=false.
library_genre_report response_format, max_results
Aggregate your saved library by user-declared genre tags. Scans all saved tracks and albums, joins each item's artists against your tag sidecar (see tag_management), and reports per-genre track/album counts plus the contributing artists. Genres are unavailable from Spotify itself, so only artists you have tagged appear here.
filter_by_genre genre, kind, response_format, max_results
List URIs of your saved tracks or albums whose artists carry a given genre tag (case-insensitive tag-name match against your sidecar). Output is directly usable as create_playlist / add_to_playlist input. Read-only.
tag_management action, artist, tags, dry_run, response_format
Declare or retract genre tags for an artist in your local sidecar (~/.spotify-mcp/genre-tags.json), which library_genre_report and filter_by_genre consume. add requires at least one tag; remove drops the listed tags, or the artist entirely when none are listed. Supports dry_run preview.
library_hygiene response_format, max_results, dry_run
Read-only album hygiene over your liked tracks: flags near-complete albums worth saving and lone singles with nothing else liked from their artist (low confidence). Album totals come from the /me/tracks walk; a width-bounded per-id GET /albums/{id} fills in the rest. Never mutates. dry_run previews cost.show_new_episodes response_format, max_results, days, per_show_limit, max_shows, cost_preview, market
Find new episodes across your saved podcast shows: reports episodes released within the lookback window (default 7 days), marking which are already saved in your episode library. Fetches /me/shows then each show's latest episodes, overlapping episode lookups (width: SPOTIFY_MCP_MAX_CONCURRENCY, else SPOTIFY_MCP_FANOUT_CONCURRENCY, else 4) so a 25-show scan is not 25 serial round trips. WARNING: M saved shows → M+1 requests (1 show page + M episode lookups). Use max_shows to budget and cost_preview to see the cost without making any calls. This tool is read-only: nothing is ever changed.
find_duplicate_saved_tracks response_format, max_results, include_near_duplicates, playlist_id
Read-only duplicate detection over your saved (liked) tracks. Exact groups require the same non-null ISRC and album id with duration within ±2s, and keep the oldest dated save. On opt-in, near-duplicate groups show same-title/artist tracks whose ISRC, release, or duration differs; these are distinct saved tracks and are review-only with no removals. Undated saves sort after dated saves. Optionally pass a playlist_id to cross-reference which group members also appear in that playlist. Never mutates your library.
plan_podcast_session minutes, kind, saved_only, market, response_format, max_results
Greedy-pack your saved podcast episodes into a listening session of a given length. Episodes play their remaining time (duration minus resume position); fully played ones are skipped. Scanning stops at the first unplayed episode that doesn't fit.
start_podcast_session minutes, kind, saved_only, device_id, market, dry_run, response_format, max_results
Plan a podcast session (see plan_podcast_session) and start it on a device. Limitation: Spotify cannot apply resume offsets when queueing — only the first episode can start at its resume point (via PUT /me/player/play on its show context); later episodes are appended to the queue and play from the beginning. With dry_run, nothing is played or queued.
backup_first notes, response_format
Create a pre-flight library snapshot before a destructive operation. Returns snapshot file path and counts for later restore. Read-only against Spotify.
backup_library notes, response_format, walk_cap, dry_run
Snapshot your ENTIRE library to a local JSON file (read-only against Spotify): liked tracks, saved albums/shows/episodes/audiobooks, followed artists, and every playlist with its items. Walks capped at SPOTIFY_MCP_FETCH_ALL_CAP (500/category) and each playlist at SPOTIFY_MCP_PLAYLIST_ITEMS_CAP (500); the smaller wins, so a full backup of a large playlist needs both raised. Files land in SPOTIFY_MCP_BACKUP_DIR (default ~/.spotify-mcp/backups), mode 0600.
list_backups response_format
List complete and partial library backups (newest first) using bounded metadata sidecar reads, with a bounded prefix fallback for legacy snapshots. Expires snapshots past SPOTIFY_MCP_BACKUP_RETENTION_DAYS (default 30, 0 disables) and reports what it removed, plus the store envelope (dir_bytes, oldest_created, oldest_retention_until).
delete_backup file, response_format, dry_run
Delete one library backup file (and its metadata sidecar) from SPOTIFY_MCP_BACKUP_DIR. Irreversible — the library rows in the file cannot be recovered from anywhere else. Destructive and confirmation-gated: dry_run defaults to true, and executing is refused when the client cannot prompt (SPOTIFY_MCP_CONFIRM=never bypasses). Paths outside the backup directory are refused.
clean_backup_artifacts family, older_than_days, files, response_format, dry_run
Delete the NON-library files sharing SPOTIFY_MCP_BACKUP_DIR with your library backups: closed listening sessions (`listening-session-*.json`), playlist write pre-images (`playlistops-pre-*.json`) and legacy or migrated playback bookmarks (`playback-bookmark-*.json`). Library backups and their `.meta.json` sidecars are never touched — use `delete_backup`, and naming one here is refused. These files are local and gone for good once deleted. Preview by default; executing is confirmation-gated and refused when the client cannot prompt (SPOTIFY_MCP_CONFIRM=never bypasses). Ages are mtimes, and the default window is SPOTIFY_MCP_BACKUP_ARTIFACT_RETENTION_DAYS — separate from the library window. Unrecognised files are listed, not deleted.
restore_library_snapshot backup_path, categories, dry_run, response_format, max_results
STRICTLY ADDITIVE restore of a library snapshot written by backup_library (see list_backups). Adds only what is missing: saves absent tracks/albums/shows/episodes/audiobooks, follows unfollowed artists, and creates NEW playlists named 'Restored · <name> (<snapshot date>)' — existing playlists are never touched and nothing is deleted, renamed, or overwritten. Truncated snapshots are previewable but refused before confirmation or writes; quota-hit, contentless or wrong-schema_version snapshots are refused outright. Prompt and result state where the stored data came from, the date the FILE declares (naming the reason when absent — never the mtime), the item count, and the single use made of it; dry_run defaults to TRUE (read-only preview); setting dry_run=false requires explicit confirmation before any write, fails closed when elicitation is unavailable or errors, and allows writes when SPOTIFY_MCP_CONFIRM=never.
undo_mutation receipt_id, response_format, dry_run
Undo a specific mutation by receipt ID. Inverts the recorded direction: an add/save is undone by removing, a removal by re-adding (playlist items or library). A playlist add undo removes only the rows it created, refusing when no row positions are recorded. The result reflects the refetched post-state. Non-reversible kinds return not reversible. Executing needs confirmation and is refused when the client cannot prompt (SPOTIFY_MCP_CONFIRM=never bypasses).
undo_last_mutation dry_run, response_format
Undo the most recent reversible mutation (receipt FIFO). Same inversion semantics as undo_mutation: add/save → remove, removal → re-add. Executing needs confirmation and is refused when the client cannot prompt (SPOTIFY_MCP_CONFIRM=never bypasses).
verify_receipt receipt_id
Verify that a previous mutation actually landed on Spotify by looking up its receipt. Receipts are session-scoped: the 100 most recent mutations, in this process only, and lost on restart unless SPOTIFY_MCP_RECEIPTS is set. An unknown or expired id returns isError with found:false — a fact about the lookup, not about the mutation.
whats_new since, days_back, kinds, max_artists, response_format, max_results, dry_run
Personal new-releases radar: derive what's new from followed artists (new albums/singles) and saved shows (new podcast episodes), replacing the removed browse/new-releases surface. WARNING: the follow list is paged 50 artists per request, so on a COLD read cache the album leg costs ceil(max_artists/50) follow pages PLUS up to max_artists album lookups (#679); a repeat scan inside the cache window re-probes the same canonical request and spends no request (#900). A large library can still exhaust small dev-account quotas in one call. Use max_artists to budget and dry_run to preview the cost before running; dry_run labels its figure a budget bound (it is arithmetic over the budget, not a measurement) and a real call reports the request count it actually issued in `cost`. Decision guide: whats_new for personal follows radar; search_fresh for query-scoped tag:new, search/search_deep for general catalog, search_by_isrc for ISRC-exact.
search_deep query, types, pages, offset, market, response_format, max_results
Paged catalog search that walks past the API limit of 10 results per type. Fetches up to 5 pages of 10 results per requested type server-side from a caller-supplied `offset`, dedupes by id, and returns compact rows. Type walks overlap (width: SPOTIFY_MCP_MAX_CONCURRENCY, else SPOTIFY_MCP_FANOUT_CONCURRENCY, else 4); same request count. Decision guide: use search_deep when you need >10 results/type or a later window; otherwise use search (single page), search_fresh (new releases), search_by_isrc (ISRC-exact), whats_new (personal follows).
save_scene name, device_hint, volume, shuffle, repeat, context_uri, response_format
Save a named playback scene (device + volume + shuffle/repeat + optional context) to the local sidecar (~/.spotify-mcp/scenes.json)
list_scenes response_format
List saved playback scenes from the local sidecar
delete_scene name, response_format
Delete a saved playback scene from the local sidecar
apply_scene name, dry_run, response_format
Apply a saved scene: resolve its device hint, transfer playback, then set volume/shuffle/repeat and start the saved context (in that order; missing targets are skipped)
schedule_wind_down minutes, step_minutes, floor_volume, device_id, response_format, dry_run
Preview or start a volume wind-down: absolute-minute volume steps, then pause. Set dry_run to preview without replacing or cancelling an active timer.
wind_down_status device_id, response_format
Read the current or most recent wind-down progress, including per-step failures
cancel_wind_down device_id, response_format
Cancel the in-process wind-down ramp, if one is running
grow_playlist playlist_id, size, exclude_saved, dry_run, response_format, max_results
Propose tracks to grow one of your playlists using ONLY your own listening data (no recommendations): finds tracks appearing in >=2 of your OTHER playlists, boosts ones sharing an artist with the target playlist, excludes tracks already in it (and optionally your saved library), and returns top candidates with evidence. Read-only: review the proposals, then call add_to_playlist with the URIs you want.
export_playlist playlist_id, format, output_path, overwrite, include_headers, response_format, max_results
Export a playlist's full item list as an M3U playlist file or a CSV spreadsheet. Pages every item; pass output_path to write a file (created with mode 0600) inside the configured output root, or omit it to get the document inline. CSV cells are formula-safe.
import_playlist playlist_id, content, input_path, format, dry_run, response_format
Parse an M3U or CSV document (the inverse of export_playlist) and append its Spotify URIs to a target playlist. Pass the document inline via content, or read it from input_path (a regular file inside the configured read roots). URIs already in the playlist are skipped, so a re-run adds nothing. Adds in batches of 100. Use dry_run=true to preview without writing. Result records the document source and the use made of it (consent_note); under 100 new URIs nothing is gated.
create_smart_playlist name, source, limit, time_range, artist_filter, unique_artists, description, public, scan_cap, response_format, dry_run
Create a playlist from rules over your own listening data: top tracks (by time range), recently played, or saved tracks — with optional artist-name filtering and a one-track-per-artist toggle. When source=saved_tracks the pool is the newest N saved tracks (N=scan_cap, default fetchAllCap=500) and truncation is reported. No deprecated recommendations endpoints involved. Every source has a pool ceiling (top_tracks 100, recently_played 50, saved_tracks scan_cap), reported as pool_capped with pool_cap — a capped pool is a floor, not a complete scan. dry_run previews the exact track list without creating anything.
search_within_playlist response_format, max_results, playlist_id, id, query, kind, market
Text search inside a single playlist: a client-side filter over the rows the walk read, cheaper than paging get_playlist_items yourself for a narrow query — but it can only see that window, so scanned_items/scan_cap/scan_truncated say how much of the playlist was actually read. Matches item name, artist, album and show name; kind narrows a mixed playlist to tracks only or episodes only. Quota: GET /playlists/{id}/items paged.search_history_stats top_n, response_format
Analytics over the local search-history sidecar: top queries, type breakdown, recency. Quota: local only (no API).
audiobook_progress audiobook_id, market, response_format
Audiobook progress rollup: chapters total, played count, current chapter, percent complete. Walks every chapter page up to the shared fetch-all cap and reports scan coverage. Quota: 1 audiobook GET + chapter page GETs.
unsave_orphan_tracks dry_run, max_remove, scan_cap, response_format
Find saved tracks that appear in no playlist (orphans) and optionally unsave them. Quota: walks library + all playlists (capped). PREVIEWS BY DEFAULT — pass dry_run=false to commit. Removing 10+ orphans additionally requires elicitation confirmation (or SPOTIFY_MCP_CONFIRM=never for automation).
playlist_to_library playlist_id, dry_run, dedupe, response_format
Save all tracks of a playlist to your Liked Songs (library). Quota: GET playlist items + PUT /me/tracks (chunked 50).
followed_playlists_audit only_followed, response_format, max_results
Inventory of followed vs owned playlists: counts, collab, public, follower totals. Quota: GET /me/playlists paged.
get_playlist_added_dates playlist_id, sort, response_format, max_results
List when each track was added to a playlist (added_at + added_by). Quota: GET /playlists/{id}/items paged.split_playlist playlist_id, parts, name_prefix, dry_run, public
Split a playlist into N chunks (new playlists). Quota: GET all + N POST /me/playlists + N POST items.
find_duplicate_tracks_across_playlists playlists, response_format, max_results
Find tracks that appear in more than one of the given playlists (cross-playlist dupes). Quota: N GETs (one per playlist).
remove_from_library_by_playlist playlist_id, dry_run, response_format
Remove from Liked Songs any tracks that also appear in a given playlist. Quota: 2 GETs + DELETE (chunked). PREVIEWS BY DEFAULT — pass dry_run=false to commit. Removing 10+ saved tracks additionally requires elicitation confirmation (or SPOTIFY_MCP_CONFIRM=never for automation).
Descriptions are the package's own words, cut at 3,000 characters. Treat them as data.
Install facts
| License | MIT |
|---|---|
| Needs | node >=22.9 |
| Source | github.com/NovaLux12/spotify-mcp-server |
| Install scripts | None declared by it or anything installed with it. |
| Tarball | sha512-JUCh+kqs8Gc8b/UWuYIU1usz/cZvMRQ7YOd6gSbKDdOzQsoDmvOj+FqRVFB0w23p4IDtLqjTmGI16eR9oc3e9g== |
Check this report yourself
This site did not write the report. A public job on a GitHub-hosted machine did: the run, from this commit of the open-source runner. GitHub signed a token that names that job and the hash of the report, so any edit since would show.
Report as JSONExact text and tokenHow to verify it
Show it on your README
[](https://bragproof.smaverk.com/r/%40novalux12/spotify-mcp)
New version out? Ask for a fresh report.