List all available Spotify playback devices for the current user.

Returns

dict Keys: devices (list of dicts with id, name, type, is_active, volume_percent).

Transfer Spotify playback to a specific device.

Parameters

device_id : str The Spotify device ID to transfer playback to.

Returns

dict {"status": "transferred", "device_id": str}

Raises

ValueError If device_id is blank. spotipy.SpotifyException Propagated if the Spotify API returns a non-2xx response.

Retrieve information about the track currently playing on Spotify.

Returns structured metadata including the track URI, which is needed by other tools such as add_to_queue and get_recommendations.

Returns

dict Keys: is_playing, track_name, artists, album, duration_ms, progress_ms, track_url, track_uri. Returns {"is_playing": False} when nothing is playing.

Raises

spotipy.SpotifyException Propagated if the Spotify API returns a non-2xx response.

Control Spotify playback – play, pause, or toggle the current state.

Parameters

action : str, optional One of "play", "pause", or "toggle" (default).

Returns

dict {"status": "playing" | "paused" | "no_active_device"}

Raises

ValueError If action is not one of the accepted values. spotipy.SpotifyException Propagated if the Spotify API returns a non-2xx response.

Skip to the next or previous track on the active Spotify device.

Parameters

direction : str, optional "next" (default) to skip forward, "previous" to go back.

Returns

dict {"status": "skipped_next" | "skipped_previous" | "no_active_device"}

Raises

ValueError If direction is not "next" or "previous". spotipy.SpotifyException Propagated if the Spotify API returns a non-2xx response.

Add a track to the user's active Spotify playback queue.

Parameters

uri : str Spotify track URI (spotify:track:<id>) or bare track ID.

Returns

dict {"status": "queued", "uri": "<full_spotify_uri>"}

Raises

spotipy.SpotifyException Propagated if the Spotify API returns a non-2xx response.

Fetch track recommendations based on a list of seed track URIs or IDs.

Note

Spotify deprecated the public recommendations endpoint in November 2024. This tool works for apps created before that date or granted continued access.

Parameters

seed_tracks : list[str] Spotify track URIs or bare IDs (max 5 seeds; excess are truncated). limit : int, optional Number of recommendations to return (1–100, default: 5).

Returns

dict Keys: seeds (list[str]), tracks (list[dict]).

Raises

ValueError If seed_tracks is empty or limit is out of range. spotipy.SpotifyException Propagated if the Spotify API returns a non-2xx response.

Fetch a paginated list of the current user's Spotify playlists.

Parameters

limit : int, optional Maximum number of playlists to return (1–50, default: 20). offset : int, optional Zero-based index of the first playlist to return (default: 0).

Returns

dict Keys: total, limit, offset, playlists.

Raises

ValueError If limit is outside [1, 50]. spotipy.SpotifyException Propagated if the Spotify API returns a non-2xx response.

Create a new empty private playlist for the current user.

Parameters

name : str Display name for the new playlist. description : str, optional Short description shown in Spotify clients (default: empty string).

Returns

dict Keys: id, name, url.

Raises

ValueError If name is blank. spotipy.SpotifyException Propagated if the Spotify API returns a non-2xx response.

Add one or more tracks to an existing Spotify playlist.

Handles batching automatically (Spotify API limit: 100 tracks per request).

Parameters

playlist_id : str Spotify playlist ID or full URI. track_uris : list[str] Spotify track URIs or bare track IDs.

Returns

dict Keys: playlist_id (str), tracks_added (int).

Raises

ValueError If track_uris is empty. spotipy.SpotifyException Propagated if the Spotify API returns a non-2xx response.

Search for a track and add the top result to a playlist in one step.

Parameters

query : str Free-text search query (e.g. "Shape of You Ed Sheeran"). playlist_id : str Spotify playlist ID or full URI to add the track to.

Returns

dict Keys: track_name, artists, track_uri, playlist_id.

Raises

ValueError If query is blank or the search returns no results. spotipy.SpotifyException Propagated if the Spotify API returns a non-2xx response.

Switch the active Spotify user profile.

Updates the server's internal state so all subsequent tool calls use the token cache for name. Each user's token lives in .cache-<name> in the project root; pass "default" to return to the primary account.

Parameters

name : str User profile name. Must have a corresponding cache file or be "default".

Returns

dict {"previous_user": str, "current_user": str}

Raises

ValueError If name is blank or no token cache exists for that profile.

Start playback of a Spotify context (playlist, album, or artist).

Parameters

context_uri : str Spotify URI (e.g. spotify:playlist:<id>) or bare playlist ID.

Returns

dict {"status": "playing", "context_uri": str}

Raises

spotipy.SpotifyException Propagated if the Spotify API returns a non-2xx response.

Generate and populate a Spotify playlist from a natural-language prompt.

Uses Claude to interpret the prompt and produce a tracklist, then creates a new playlist and searches for each track on Spotify.

Parameters

prompt : str Natural-language description, e.g. "10 summer hits from 2024". playlist_name : str, optional Name for the new playlist. If omitted, Claude will suggest one.

Returns

dict Keys: playlist_id, playlist_name, playlist_url, tracks_added (int), tracks_not_found (list[str]).

Raises

EnvironmentError If GEMINI_API_KEY is not configured. ValueError If prompt is blank.