Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SPOTIFY_ACCESS_TOKEN | Yes | Your Spotify API access token with required scopes (playlist-modify-public, playlist-modify-private, playlist-read-private, user-read-private) |
Schema
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| spotify_get_recommendations | Get track recommendations from Spotify based on seed tracks, artists, or genres. Generates personalized recommendations using up to 5 seeds (any combination) with
tunable audio features (energy, danceability, valence, tempo).
Args:
- seed_tracks/seed_artists/seed_genres: Up to 5 total seeds (track IDs, artist IDs, or genre names)
- limit: Results to return, 1-100 (default: 20)
- min/max/target audio features: Energy, danceability, valence (0.0-1.0), tempo (BPM)
- response_format: 'markdown' (formatted) or 'json' (structured data)
Returns:
Markdown: Numbered list with track details (name, artists, album, duration, ID, popularity)
JSON: {"total": N, "tracks": [{id, name, artists, album, duration_ms, popularity, uri, external_urls}]}
Examples:
- "Find energetic workout music" -> seed_genres=['electronic'], target_energy=0.9
- "Songs like this track" -> seed_tracks=['track_id']
- "Happy danceable songs" -> target_valence=0.8, target_danceability=0.8
Errors: Returns error for no seeds, >5 seeds, auth failure (401), rate limits (429), or no results. |
| spotify_create_playlist | Create a new empty Spotify playlist for the authenticated user. Creates an empty playlist in the user's library. Use spotify_add_tracks_to_playlist
to add tracks after creation.
Args:
- name: Playlist name, 1-100 characters
- description: Optional description, max 300 characters
- public: Whether playlist is public (default: True)
- collaborative: Whether others can modify (default: False, cannot be True if public is True)
Returns:
JSON: {"success": true, "playlist_id": "...", "name": "...", "url": "...", "message": "..."}
Examples:
- "Create a new workout playlist" -> name="Workout Mix"
- "Make a private playlist" -> name="My Mix", public=False
- "Create collaborative playlist" -> collaborative=True, public=False
Errors: Returns error for collaborative+public, auth failure (401), missing scopes (403), rate limits (429). |
| spotify_add_tracks_to_playlist | Add tracks to an existing Spotify playlist. Adds 1-100 tracks to a playlist. Tracks can be inserted at a specific position or
appended to the end. Playlist must be owned by user or be collaborative.
Args:
- playlist_id: Spotify playlist ID (not URI)
- track_uris: List of track URIs, 1-100 (format: "spotify:track:ID", not just IDs)
- position: Optional 0-indexed position to insert (default: append to end)
Returns:
JSON: {"success": true, "snapshot_id": "...", "tracks_added": N, "message": "..."}
Examples:
- "Add this track to my playlist" -> track_uris=["spotify:track:ID"], playlist_id="..."
- "Add 10 songs to workout mix" -> track_uris=[list of URIs]
- "Insert at the beginning" -> position=0
Errors: Returns error for invalid playlist (404), no permission (403), auth failure (401), rate limits (429). |
| spotify_get_user_playlists | Get a list of the current user's Spotify playlists. Retrieves all playlists owned by or followed by the authenticated user. Results are
paginated. Use to browse playlists or find playlist IDs.
Args:
- limit: Number of playlists to return, 1-50 (default: 20)
- offset: Starting position for pagination (default: 0)
- response_format: 'markdown' or 'json'
Returns:
Markdown: List with playlist name, ID, track count, public status, description, URL
JSON: {"total": N, "count": N, "offset": N, "playlists": [{id, name, description, public, collaborative, tracks, owner, external_urls}], "has_more": bool}
Examples:
- "Show me my playlists" -> List all user playlists
- "Find my workout playlist" -> Browse to find specific one
- Need playlist ID -> Get ID from the list
Errors: Returns "No playlists found." if none exist, or error for auth failure (401), missing scopes (403), rate limits (429). |
| spotify_get_playlist_tracks | Get tracks from a specific Spotify playlist. Retrieves tracks from a playlist with detailed information (artists, album, duration, IDs).
Results are paginated for large playlists.
Args:
- playlist_id: Spotify playlist ID (get from spotify_get_user_playlists or playlist URL)
- limit: Number of tracks to return, 1-50 (default: 20)
- offset: Starting position for pagination (default: 0)
- response_format: 'markdown' or 'json'
Returns:
Markdown: Numbered list with track details (name, artists, album, duration, ID, URI, popularity)
JSON: {"total": N, "count": N, "offset": N, "tracks": [{id, name, artists, album, duration_ms, popularity, uri, external_urls}], "has_more": bool}
Examples:
- "Show me what's in my workout playlist" -> View playlist contents
- "Get track IDs from this playlist" -> Extract IDs for operations
Errors: Returns "No tracks found" if empty, or error for invalid playlist (404), auth failure (401), rate limits (429). |
| spotify_search_tracks | Search for tracks on Spotify by name, artist, album, or keywords. Searches Spotify's entire catalog using intelligent matching. Results ranked by relevance.
Args:
- query: Search text, 1-200 chars (e.g., "Bohemian Rhapsody", "artist:Queen", "album:...", or keywords)
- limit: Results to return, 1-50 (default: 20)
- offset: Starting position for pagination (default: 0)
- response_format: 'markdown' or 'json'
Returns:
Markdown: Search results with track details (name, artists, album, duration, ID, URI, popularity)
JSON: {"total": N, "count": N, "offset": N, "tracks": [{id, name, artists, album, duration_ms, popularity, uri, external_urls}], "has_more": bool}
Examples:
- "Find Bohemian Rhapsody by Queen" -> query="Bohemian Rhapsody Queen"
- "Search for songs by Taylor Swift" -> query="artist:Taylor Swift"
- "Look for indie rock songs" -> query="indie rock"
Errors: Returns "No tracks found" if no results, or error for auth failure (401), rate limits (429). Truncates if exceeds character limit. |
| spotify_get_track | Get detailed information about a specific Spotify track by ID. Retrieves comprehensive metadata for a single track including artists, album, duration,
popularity, URIs, and external URLs.
Args:
- track_id: Spotify track ID (not URI), extract from URIs or search results
- response_format: 'markdown' or 'json'
Returns:
Markdown: Track details (name, artists, album, duration, ID, URI, popularity)
JSON: Full API response (id, name, artists, album, duration_ms, popularity, uri, external_urls, preview_url, track_number, disc_number, explicit, available_markets)
Examples:
- "Get details for track ID 4u7EnebtmKWzUH433cf5Qv" -> Retrieve track info
- "Show me info about this track" -> When you have the track ID
Errors: Returns error for invalid track (404), auth failure (401), rate limits (429). |
| spotify_get_audio_features | Get detailed audio analysis features for one or more Spotify tracks. Retrieves sonic characteristics (energy, tempo, danceability, valence, acousticness, etc.)
that power the similarity engine. Supports batch processing of up to 100 tracks.
Args:
- track_ids: List of Spotify track IDs, 1-100 tracks
- response_format: 'markdown' or 'json' (default: JSON)
Returns:
Markdown: Per-track audio features (acousticness, danceability, energy, instrumentalness, liveness, loudness, speechiness, valence, tempo, key, mode, time_signature)
JSON: {"track_count": N, "features": [{id, acousticness, danceability, energy, instrumentalness, liveness, loudness, speechiness, valence, tempo, key, mode, time_signature, duration_ms, analysis_url, track_href, type, uri}]}
Examples:
- "Analyze the audio features of this track" -> Get sonic characteristics
- "What's the tempo and energy of these songs?" -> Extract specific features
Errors: Returns "No audio features available" if not found, or error for auth failure (401), rate limits (429). Note: Audio features endpoint deprecated for NEW apps (Nov 2024), but existing apps with extended mode access can still use it. |
| spotify_find_similar_tracks | Find tracks similar to a track, artist, or playlist using audio analysis or genre matching. Centerpiece of the similarity engine. Supports 8 strategies, custom weighting, and automated
playlist creation. For curated playlists, music discovery, and mood-based mixes.
Args:
Source (one required): track_id, artist_id, or playlist_id
Strategy (default: euclidean): euclidean, weighted (needs weights), cosine, manhattan,
energy_match (workout), mood_match (relaxation), rhythm_match (running), genre_match (non-catalog scope only)
Scope (default: catalog): catalog (recommendations API), playlist (needs scope_id),
artist (needs scope_id), album (needs scope_id), saved_tracks
Action (default: return_tracks): return_tracks, create_playlist (needs playlist_name),
add_to_playlist (needs target_playlist_id)
- limit: Results to return, 1-100 (default: 20)
- min_similarity: Optional threshold, 0.0-1.0
- weights: Optional custom weights for 'weighted' strategy (e.g., {"energy": 5.0, "danceability": 5.0})
- response_format: 'markdown' or 'json'
Returns:
return_tracks: List with similarity scores (Markdown or JSON: {"strategy": "...", "scope": "...", "count": N, "tracks": [{track, similarity}]})
create_playlist: {"success": true, "action": "create_playlist", "playlist_id": "...", "playlist_name": "...", "playlist_url": "...", "tracks_added": N, "message": "..."}
add_to_playlist: {"success": true, "action": "add_to_playlist", "playlist_id": "...", "tracks_added": N, "message": "..."}
Examples:
- "Find songs similar to this track" -> track_id, catalog scope
- "Create workout playlist like this" -> track_id, energy_match, create_playlist
- "Filter playlist by genre" -> track_id, genre_match, playlist scope
- "Custom similarity for energy/dance" -> weighted strategy, custom weights
Errors: Returns errors for missing source, missing scope_id, missing action params, genre_match with catalog, no genres, no matches, auth (401), permissions (403), rate limits (429). |