Spotify MCP & Soundtrack Curator — Tool Guide & Documentation

⚡ Full Capabilities Directory

How Every Tool Works in Web & Agent

Explore the comprehensive index of all MCP tools, web studio features, and autonomous skills. Learn how requests flow from conversational LLMs or the interactive web interface into Spotify and TMDB APIs.

● 115 MCP Tools

● Dual Paradigm (Web UI + AI Agent)

● Cross-Platform (Spotify + TMDB Sync)

⚠️ Spotify 2026 Development Mode Limits

Applies to every personal Client ID

In 2026 Spotify switched off several Web API features for apps in Development Mode. The tools below work around them where they can:

Spotify feature	Status	What the tools do instead
Related artists	Removed	Related artists are the artists who share the most songs with the artist (collaborators).
Recommendations & genre seeds	Removed	Recommendations are songs by the seeds' collaborators plus genre-search picks. Genre Explorer uses a built-in genre list.
Artist top tracks	Removed	The artist's top search results stand in.
Audio features (energy, valence, tempo…)	Removed	`get_audio_features` and `reorder_playlist_by_audio_features` return an "unavailable" message. Energy and valence targets pick the genres with the closest estimated vibe; other `target_*` values are ignored. Moods map to genres.
Popularity, followers, genres	Empty	Shown as N/A or left out. Deep cuts are album tracks outside the artist's top search results.
Other users' profiles & follower checks	Removed	Profile and follower tools work for your own account only. Playlists you don't own or follow can't be read.

Dual-Execution Paradigm: Web UI vs. MCP Agent

Unified Python Backend (FastMCP + FastAPI)

🌐 Mode 1: Interactive Web Studio

→ Visual Interface: Run at http://127.0.0.1:8000. Users explore filmographies, audition song previews, and discover music by mood or genre.
→ Send Box (Staging Crate): A local staging area to collect songs from multiple movies/artists before batch-exporting to Spotify.
→ REST Endpoints: Communicates via FastAPI endpoints (e.g. /api/recommendations, /api/playlist/shuffle).

🤖 Mode 2: MCP AI Agent (Claude, Cursor, Cline)

→ Natural Language: Users talk directly to the agent (e.g., "Make a dark energetic synthwave mix").
→ Autonomous Reasoning: The LLM translates user vibe adjectives into seeds, mood presets and genres.
→ Tool Chaining: Agent chains tools seamlessly: searches TMDB $\rightarrow$ finds the soundtrack on Spotify $\rightarrow$ creates playlist $\rightarrow$ adds tracks.

✨

Vibe & Mood Recommendations

get_recommendations / POST /api/recommendations

MCP Tool Web Modal POST API

Generates a set of tracks from up to 5 combined seeds (genres, track IDs, artist IDs). Spotify removed its recommendations endpoint and audio features for Development Mode apps, so recommendations are songs by the seed artists' collaborators plus picks from a genre search. Audio targets (energy, valence, tempo) are accepted but ignored.

🌐 In the Web UI

Click the ✨ Vibe button in the top control bar to open the modal dialog. Enter comma-separated seed genres, tracks or artists. The audio sliders no longer change the results.

Submitting sends a payload to /api/recommendations and renders matching songs directly into the studio grid for previewing and staging.

🤖 In the AI Agent

The agent translates text prompts like "Give me uplifting dance music like Dua Lipa" into seeds:

get_recommendations(seed_artists=["Dua_Lipa_ID"], seed_genres=["dance pop"])

1 The Core Inputs It Accepts

To generate recommendations, the tool takes up to 5 Seed Anchors:

🌱 Seed Anchors (1 to 5 total)

seed_tracks Track IDs; the track's lead artist becomes a seed
seed_artists Artist IDs; songs by their collaborators are recommended
seed_genres Any genre keyword (e.g. synthwave, indie pop, lo-fi, house)

🎚️ Vibe Targets (0.0 to 1.0)

target_energy, target_valence When no seed genres are given, these pick the genres whose estimated energy and valence are closest.
target_danceability, target_acousticness, target_instrumentalness, target_tempo Accepted but ignored: Spotify no longer provides audio features to Development Mode apps. The output notes when they were ignored.

2 How Vibe & Type Recommendations Work in Practice

When you prompt your AI client (like Claude Desktop or Cursor), the LLM translates your natural language into seeds or a mood preset:

⚡ Scenario A: Vibe-Based Matching

Prompt: "Give me 10 songs with a dark, energetic synthwave vibe like Blinding Lights by The Weeknd."

Tool Call Executed:

seed_tracks: ["Blinding_Lights_ID"]
seed_genres: ["synthwave"]

get_recommendations(seed_tracks=["Blinding_Lights_ID"], seed_genres=["synthwave"], limit=10)

🌙 Scenario B: Mood Matching

Prompt: "Find late-night study songs, mostly instrumental."

Tool Call Executed:

mood: "focus" (ambient + classical)

spotify_discover_by_mood(mood="focus", limit=20)

3 What It Does vs. What It Doesn't Do

Capability	Status	Explanation
Artist & Track Seeds	Built-in	Recommends songs by the artists the seeds share songs with (their collaborators).
Genre Seeding	Built-in	Searches Spotify with a `genre:` filter, falling back to a plain search for the genre name.
Numeric Vibe Targets	Estimated	Spotify no longer provides per-track audio features, so energy and valence targets are matched against estimated values per genre. Danceability, acousticness and tempo can't be applied.
Text Tag Matching	LLM-Driven	Doesn't search plain-text tags like `#workout` directly; instead, the attached LLM maps text tags (e.g. "upbeat workout") to a mood preset or genres (`mood="workout"`, `seed_genres=["edm"]`).

🎬

Movie Soundtrack Search

search_movie_soundtracks(movie_title, limit)

MCP Tool Web Search

Cross-references The Movie Database (TMDB) with Spotify's catalog. Retrieves official movie metadata, release year, poster art, and pulls official OST and score albums with complete song tracklists.

🌐 In the Web UI

Select 🎬 Movies tab on the home screen, type any movie title (e.g. Interstellar, Inception), and hit Explore. Click any movie card to instantly expand its soundtrack tracks into your crate.

🤖 In the AI Agent

Say: "Find the soundtrack tracks for Oppenheimer". The agent calls this tool to retrieve songs, album URIs, and Spotify links.

search_movie_soundtracks(movie_title="Oppenheimer", limit=20)

🎭

Actor Filmography & Discography

search_actors_filmography(actor_name)

MCP Tool Web Mode

Queries TMDB for an actor or actress's complete filmography, returning movies sorted by release date and popularity. Allows one-click discovery of the music from their entire cinematic career.

🌐 In the Web UI

Switch to 🎭 Actors mode in the top tab bar, search for an actor (e.g. Ryan Gosling, Zendaya), and browse their movies. Clicking any movie loads its associated Spotify soundtrack.

🤖 In the AI Agent

Ask: "What movies was Timothée Chalamet in and give me songs from them?" The agent retrieves his filmography and discovers relevant OSTs.

search_actors_filmography(actor_name="Timothée Chalamet")

📦

Send Box (Staging Crate)

create_playlist + add_songs_to_playlist

Web Feature MCP Batch

A persistent staging crate where users collect individual tracks across movies, singers, and vibe recommendations. Once staged, users can export the crate into a brand new Spotify playlist or append into an existing one with one click.

🌐 In the Web UI

Click + Send on any track card to stage it into the right-hand Send Box sidebar. Give your playlist a title and click Create Playlist to push directly into your Spotify account.

🤖 In the AI Agent

The agent performs equivalent batch staging automatically when you ask: "Create a playlist called Cyberpunk Night and add these 10 tracks."

create_playlist(name="Cyberpunk Night", description="Curated via MCP")

🔀

Playlist Shuffler

shuffle_playlist_tool / POST /api/playlist/shuffle

MCP Tool Home Page

Randomizes track order in a playlist using cryptographic-grade random shuffling. Offers two execution modes: Create New Shuffled Playlist (non-destructive) or In-Place Reorder (for playlists you own).

🌐 In the Web UI

On the home page, click Fetch Playlist, open the 👤 My Playlists tab, and click 🔀 Shuffle next to a playlist. Its songs are saved, in a new random order, to a new playlist.

🤖 In the AI Agent

Prompt: "Shuffle my Chill Vibes playlist into a new playlist." The agent handles the track retrieval, random permutation, and playlist generation.

shuffle_playlist_tool(playlist_id="spotify:playlist:...", in_place=False)

🧹

Playlist Duplicate Remover

deduplicate_playlist / POST /api/playlist/dedupe

MCP Tool Advanced Tools

Scans any Spotify playlist for identical songs (matching song title + artist name) and removes duplicate occurrences in-place, keeping only the first instance of each track.

🌐 In the Web UI

Open /tools, select the target playlist in the 🧹 Playlist Duplicate Remover card, and click Remove Duplicates.

🤖 In the AI Agent

Say: "Clean up my Roadtrip playlist and remove all duplicate songs."

deduplicate_playlist(playlist_id="spotify:playlist:...")

🔗

Playlist Combiner

combine_playlists / POST /api/playlist/combine

MCP Tool Advanced Tools

Combines tracks from two or more playlists into a single unified playlist. Automatically handles pagination for large playlists and prevents duplicates across the combined result.

🌐 In the Web UI

Under /tools, add rows for each playlist you wish to combine, specify a name for the new composite playlist, and click Combine Playlists.

🤖 In the AI Agent

Say: "Merge my Workout playlist and Running playlist into Marathon Mix."

combine_playlists(playlist_ids=["id1", "id2"], new_name="Marathon Mix")

📁

Playlist Operations (12 Spotify Tools)

spotify_get_my_playlists, spotify_get_playlist, spotify_get_playlist_tracks, spotify_create_playlist, spotify_add_to_playlist, spotify_remove_from_playlist, spotify_reorder_playlist, spotify_update_playlist, spotify_follow_playlist, spotify_unfollow_playlist, spotify_get_playlist_cover, spotify_check_playlist_followers

12 MCP Tools UI Playlist Inspector

Complete programmatic lifecycle management for Spotify playlists. Fetch user libraries, inspect full playlist metadata, paginate tracks, create empty playlists, add or remove tracks, move and reorder track positions in real-time, modify descriptions/privacy, follow or unfollow playlists, retrieve cover art, and check follower statuses.

🌐 In the Web UI

Advanced Tools (/tools): Open the Playlist Manager & Track Inspector section to inspect any playlist, view cover art, edit name and description, toggle follow/unfollow, move tracks up/down with live reordering, remove unwanted songs, or add new track URIs.

Soundtrack Studio (/): Use the Fetch Playlist modal to browse your playlists, view all songs, and stage them directly into your Send Box.

🤖 In the AI Agent

Autonomous and prompt-driven playlist management examples:

spotify_get_my_playlists(limit=20) # Browse your library

spotify_create_playlist(name='Cinematic Soundscapes', public=True)

spotify_reorder_playlist(playlist_id='...', range_start=5, insert_before=0)

spotify_follow_playlist(playlist_id='...') # Save to library

spotify_remove_from_playlist(playlist_id='...', uris=['spotify:track:...'])

⚡

Playlist Power Tools (8 Spotify Tools)

spotify_merge_playlists, spotify_split_playlist_by_artist, spotify_deduplicate_playlist, spotify_export_playlist, spotify_playlist_diff, spotify_find_playlist_overlaps, spotify_find_playlist_subsets, spotify_absorb_playlist

8 MCP Tools Web Power Suite

Advanced algorithmic playlist manipulation and intelligence suite. Merge multiple playlists into new or existing destinations, split tracks into sub-playlists by artist, perform deep multi-strategy deduplication, export full playlist data and track metadata to structured JSON, compare playlists side-by-side with Jaccard similarity metrics, detect cross-playlist track overlaps, discover redundant subset playlists, and absorb missing songs without duplicates.

🌐 In the Web UI

Power Tools (/tools): Open the ⚡ Playlist Power Tools tabbed console to visually merge playlists, split by artist with preview breakdown, run dry-run or live deduplication, compare playlists with Venn metric badges, detect library-wide overlaps and redundant subsets, absorb unique songs, and download complete JSON backups.

🤖 In the AI Agent

Execute advanced playlist workflows directly through natural language:

spotify_merge_playlists(playlist_ids=['id1', 'id2'], new_name='Mega Mix')

spotify_split_playlist_by_artist(playlist_id='...', min_tracks_per_artist=3)

spotify_deduplicate_playlist(playlist_id='...', strategy='name_and_artist')

spotify_playlist_diff(playlist_id_a='...', playlist_id_b='...')

spotify_find_playlist_overlaps(limit=20, min_overlap=3)

spotify_find_playlist_subsets(threshold=1.0) # Detect 100% subsets

spotify_absorb_playlist(source_playlist_id='...', target_playlist_id='...')

spotify_export_playlist(playlist_id='...')

🗂️

Local Library Cache & Playlist Generators (7 Tools)

spotify_sync_library, spotify_library_stats, spotify_query_library, spotify_vibe_playlist, spotify_radio_playlist, spotify_era_playlist, spotify_time_capsule_playlist

7 MCP Tools Agent Only

spotify_sync_library saves your Liked Songs and the playlists you own to a local JSON file (~/.cache/spotify-mcp/library.json, or %LOCALAPPDATA%\spotify-mcp\library.json on Windows). Queries and stats then run without calling Spotify. The generators build vibe, artist-radio, era and time-capsule playlists, using your cached songs where that helps. They show a preview first and only create the playlist when called with create=True.

🧠 How Vibes Are Estimated

Spotify no longer gives this app audio features or artist genres. Each genre has an estimated energy and valence, and a song gets a vibe from the genre searches its artist appears in, plus words in its track, album and playlist names (a playlist called "Gym" means workout). Songs nothing can be inferred about are skipped. Spotify's genre search mostly covers mainstream Western genres, so naming your playlists by mood helps most for other scenes.

🤖 In the AI Agent

spotify_sync_library()

spotify_vibe_playlist(mood="workout", from_library=True, create=True)

spotify_radio_playlist(seed="A. R. Rahman", limit=30)

spotify_era_playlist(start_year=1990, end_year=1999, genres=["rock"])

spotify_time_capsule_playlist(year=2021)

🔮

Search, Recommendations & Discovery (7 Spotify Tools)

spotify_search, spotify_related_artists, spotify_discover_by_artist, spotify_discover_by_mood, spotify_genre_explorer, spotify_discover_deep_cuts, spotify_get_recommendations

7 MCP Tools Web Discovery Suite

Complete catalog search across tracks, artists, albums, and playlists; finding connected artists (the ones who share songs with an artist) and recommending their songs; mood presets mapped to genres; sampling tracks by genre; digging for album deep cuts; and seed-based recommendations. Spotify removed related artists, recommendations, genre seeds, top tracks and audio features for Development Mode apps, so these tools rebuild them from search and album data.

🖥️ How to Use in Web Studio

Open the Search, Recommendations & Discovery Studio on the home page (/).
Use Universal Search to search tracks, artists, albums, and playlists with one query.
Use Related Artists & Artist Network to find the artists who share songs with a musician.
Click Mood Discovery to select emotional presets (Happy, Chill, Energetic, Focus, Party, Dark, Workout); each maps to genres.
Browse Genre Explorer to sample tracks from the built-in genre list or any genre keyword.
Run Deep Cuts Finder on an artist or album to unearth album tracks that aren't among their top search results.

🤖 How to Use with AI Agent (Prompts)

spotify_search(query='Daft Punk', types=['track', 'artist', 'album'])

spotify_related_artists(artist='Hans Zimmer')

spotify_discover_by_artist(artist='Coldplay', limit=15)

spotify_discover_by_mood(mood='chill', limit=20)

spotify_genre_explorer(genres=['synthwave', 'lo-fi'], limit=15)

spotify_discover_deep_cuts(artist_or_album='Radiohead', limit=15)

spotify_get_recommendations(seed_genres=['jazz'], limit=20)

📊

Audio Features & Vibe Sorter

get_audio_features / reorder_playlist_by_audio_features

Unavailable Agent Skill

Spotify no longer provides audio features (valence, energy, danceability, tempo, key) to Development Mode apps, so these two tools only return an "unavailable" message and never change your playlist. They stay registered so existing prompts get a clear answer instead of an error.

🌐 In the Web UI

The audio-feature inspector and Smart Sorter were removed from the web studio.

🤖 In the AI Agent

The playlist_vibe_sorter skill explains the limit and offers what still works: manual reordering, shuffle, splitting by artist, or a new mood playlist.

spotify_reorder_playlist(playlist_id="...", range_start=10, insert_before=0, range_length=5)

🎛️

Playback Control & Status (15 Spotify Tools)

spotify_status, spotify_now_playing, spotify_play, spotify_pause, spotify_resume, spotify_skip_next, spotify_skip_previous, spotify_add_to_queue, spotify_get_queue, spotify_get_devices, spotify_transfer_playback, spotify_set_volume, spotify_seek, spotify_set_repeat, spotify_toggle_shuffle

15 MCP Tools Interactive UI Player

Full Spotify Connect integration for hardware, mobile, and desktop playback control. Manage play, pause, resume, track navigation, queue inspection, device transfers, volume, seeking, repeat modes, and shuffle toggling hands-free through AI agents or through the interactive floating Web UI player.

🌐 In the Web UI

Floating Player Widget: Displays currently playing album art, song title, artist, live time elapsed, interactive click-to-seek timeline bar, play/pause, skip previous/next, shuffle toggle, repeat mode (off/all/1), active device badge, and quick device & queue modal triggers.

Device Picker Modal: Scans all active Spotify Connect devices (desktop, phone, smart speakers) and allows one-click playback transfer.

Live Queue Inspector: Real-time view of currently playing track and upcoming queue songs, with instant play and batch queueing from your Send Box.

🤖 In the AI Agent

Control Spotify hands-free using natural language prompts or direct tool calls:

spotify_now_playing() # Returns title, artist, progress & device

spotify_play(uri="spotify:track:...") # Play track or context

spotify_set_volume(volume_percent=45) # Set volume 0-100

spotify_toggle_shuffle(state=True) # Toggle shuffle

spotify_transfer_playback(device_id="...", play=True)

spotify_get_queue() # Inspect queue & up next songs

🏷️

Web & Browser Song Tagger

browser_song_tagger skill

Agent Skill Autonomous

An autonomous agent skill that researches obscure songs via web search (DuckDuckGo or browser tools) to discover niche genres, cultural tags, and aesthetic sub-genres, then applies those tags to Spotify playlist metadata.

🌐 In the Web UI

Tags extracted by the agent are reflected in playlist descriptions and used to populate seed genre inputs inside the Vibe Modal.

🤖 In the AI Agent

Ask: "Check the web tags for 'Resonance' by HOME and add it to a matching tag playlist." The agent searches the web, finds Synthwave, Chillwave, and stages it.

Agent conducts Web Search -> tags as Synthwave -> categorizes playlist

📊

Stats, Analytics & Insights Studio

spotify_top_tracks, spotify_top_artists, spotify_recently_played, spotify_listening_patterns, spotify_taste_profile, spotify_playlist_compare, spotify_playlist_freshness

7 MCP Tools Web Studio REST APIs

A listening telemetry and comparison studio. Inspect personal short, medium, and long term track/artist affinity, hourly volume curves, your taste profile (top artists, artist variety, eras), side-by-side playlist comparisons, and playlist freshness audits. Spotify no longer returns audio features, popularity or genres to Development Mode apps, so there are no energy, valence or mainstream scores.

🌐 In the Web UI (/tools)

Access the 📊 Stats, Analytics & Insights Studio with interactive tabs for Top Tracks, Top Artists, Recently Played, Listening Patterns (with 24-hr bar chart), Taste Profile, Multi-Playlist Compare, and Freshness Audit.

🤖 In the MCP AI Agent

Call granular analytical tools directly:

spotify_top_tracks(time_range="medium_term", limit=10)

spotify_listening_patterns(limit=50) # Peak hours & days

spotify_taste_profile() # Listener type, top artists, eras

spotify_playlist_compare(playlist_ids=["id1", "id2"])

spotify_playlist_freshness(stale_days_threshold=60)

📚

Library & Liked Media Studio

spotify_get_saved_tracks, spotify_save_tracks, spotify_remove_saved_tracks, spotify_check_saved_tracks, spotify_get_saved_albums, spotify_save_albums, spotify_remove_saved_albums, spotify_check_saved_albums

8 MCP Tools Web Studio REST APIs

Complete management of your Spotify personal library. Read, batch-save, unlike, and verify membership of individual tracks in your Liked Songs, or manage your saved album collection.

🌐 In the Web UI (/tools)

Access the 📚 Library & Saved Media Studio with dedicated tabs for browsing Liked Songs, batch-saving tracks, checking like status, browsing saved albums, and managing your album library.

🤖 In the MCP AI Agent

Interact with user library items programmatically:

spotify_get_saved_tracks(limit=20, offset=0)

spotify_save_tracks(track_ids=["spotify:track:..."])

spotify_check_saved_tracks(track_ids=["id1", "id2"])

spotify_get_saved_albums(limit=10)

spotify_save_albums(album_ids=["spotify:album:..."])

🔎

Catalog & Entity Inspection (Browse) Studio

spotify_get_track, spotify_get_album, spotify_get_artist, spotify_get_artist_albums, spotify_get_user

5 MCP Tools Web Studio REST APIs

Deep-dive inspection into Spotify catalog entities. Inspect detailed track metadata (ISRC codes, 30s audio previews), full album information (record label, legal copyrights, full tracklists), artist profiles, complete discographies (albums, singles, compilations), and your own user profile. Spotify no longer returns popularity, followers or genres, or other users' profiles, to Development Mode apps; those fields show N/A.

🌐 In the Web UI (/tools)

Access the 🔎 Catalog & Entity Inspection Studio with dedicated tabs for Track Details (with audio preview playback), Album Details (with copyright and tracklist), Artist Profile, and Discography.

🤖 In the MCP AI Agent

Inspect any Spotify entity directly by ID, URI, or name:

spotify_get_track(track_id="spotify:track:4cOdK2wGLETKBW3PvgPWqT")

spotify_get_album(album_id="spotify:album:4aawyAB9vmqN3uQ7FjRGTy")

spotify_get_artist(artist_id="Radiohead")

spotify_get_artist_albums(artist_id="Daft Punk", include_groups="album,single")

spotify_get_user(user_id="me")

No tools found matching your search

Try searching for "vibe", "tmdb", "shuffle", "volume", or reset your category filter.