Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SPOTIFY_CLIENT_ID | Yes | Your Spotify Client ID from developer.spotify.com | |
| SPOTIFY_REDIRECT_URI | No | The redirect URI configured in your Spotify app | http://localhost:8888 |
| SPOTIFY_CLIENT_SECRET | Yes | Your Spotify Client Secret from developer.spotify.com |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| playback_control | Control Spotify playback. Args:
action: Action ('get', 'start', 'pause', 'skip')
track_id: Track ID to play (for 'start')
num_skips: Number of tracks to skip |
| search_tracks | Search Spotify for tracks, albums, artists, or playlists. Args:
query: Search query
qtype: Type ('track', 'album', 'artist', 'playlist')
limit: Max results per page (1-50, default 10)
offset: Number of results to skip for pagination (default 0)
year: Filter by year (e.g., '2024')
year_range: Filter by year range (e.g., '2020-2024')
genre: Filter by genre (e.g., 'electronic', 'hip-hop')
artist: Filter by artist name
album: Filter by album name
Returns:
Dict with 'items' (list of tracks) and pagination info ('total', 'limit', 'offset')
Note: Filters use Spotify's search syntax. For large result sets, use offset to paginate.
Example: query='love', year='2024', genre='pop' searches for 'love year:2024 genre:pop' |
| add_to_queue | Add a track to the playback queue. Args:
track_id: Spotify track ID to add to queue
Returns:
Dict with status and message |
| get_queue | Get the current playback queue. Returns: Dict with currently_playing track and queue of upcoming tracks |
| get_track_info | Get detailed information about one or more Spotify tracks. Args:
track_ids: Single track ID or list of track IDs (up to 50)
Returns:
Dict with 'tracks' list containing track metadata including release_date.
For single ID, returns {'tracks': [track]}.
Note: Batch lookup is much more efficient - 50 tracks = 1 API call instead of 50. |
| get_artist_info | Get detailed information about a Spotify artist. Args:
artist_id: Spotify artist ID
Returns:
Dict with artist info and top tracks |
| get_playlist_info | Get basic information about a Spotify playlist. Args:
playlist_id: Spotify playlist ID
Returns:
Dict with playlist metadata (no tracks - use get_playlist_tracks for tracks)
Note: This returns playlist info only. For tracks, use get_playlist_tracks
which supports full pagination for large playlists. |
| create_playlist | Create a new Spotify playlist. Args:
name: Playlist name
description: Playlist description (default: empty)
public: Whether playlist is public (default: True)
Returns:
Dict with created playlist information |
| add_tracks_to_playlist | Add tracks to a playlist. Args:
playlist_id: Playlist ID
track_uris: List of track URIs (up to 100) |
| get_user_playlists | Get current user's playlists with pagination support. Args:
limit: Max playlists to return per page (1-50, default 20)
offset: Number of playlists to skip for pagination (default 0)
Returns:
Dict with 'items' (list of playlists) and pagination info ('total', 'limit', 'offset')
Note: For users with many playlists, use offset to paginate through results.
Example: offset=0 gets playlists 1-20, offset=20 gets playlists 21-40, etc. |
| get_playlist_tracks | Get tracks from a playlist with full pagination support. Args:
playlist_id: Playlist ID
limit: Max tracks to return (None for all tracks, up to 10,000 safety limit)
offset: Number of tracks to skip for pagination (default 0)
Returns:
Dict with 'items' (list of tracks), 'total', 'limit', 'offset'
Note: Large playlists require pagination. Use limit/offset to get specific ranges:
- Get first 100: limit=100, offset=0
- Get next 100: limit=100, offset=100
- Get all tracks: limit=None (use with caution on very large playlists) |
| remove_tracks_from_playlist | Remove tracks from a playlist. Args:
playlist_id: Playlist ID
track_uris: List of track URIs to remove |
| modify_playlist_details | Modify playlist details. Args:
playlist_id: Playlist ID
name: New playlist name (optional)
description: New playlist description (optional)
public: Whether playlist should be public (optional) |
| get_album_info | Get detailed information about a Spotify album. Args:
album_id: Spotify album ID
Returns:
Dict with album metadata including release_date, label, tracks |
| get_audio_features | Get audio features for one or more tracks (tempo, key, energy, danceability, etc). Args:
track_ids: Single track ID or list of track IDs (up to 100)
Returns:
Dict with 'features' list containing audio features for each track.
Features include: tempo, key, mode, time_signature, danceability, energy,
valence, loudness, speechiness, acousticness, instrumentalness, liveness.
Note: Batch lookup is efficient - 100 tracks = 1 API call. |
| get_saved_tracks | Get user's saved/liked tracks (Liked Songs library). Args:
limit: Max tracks to return per page (1-50, default 20)
offset: Number of tracks to skip for pagination (default 0)
Returns:
Dict with 'items' (list of tracks with added_at timestamp) and pagination info |
| get_recommendations | Get track recommendations based on seed artists, tracks, or genres. Args:
seed_artists: List of artist IDs (up to 5 total seeds combined)
seed_tracks: List of track IDs (up to 5 total seeds combined)
seed_genres: List of genres (up to 5 total seeds combined)
limit: Number of recommendations to return (1-100, default 20)
Returns:
Dict with 'tracks' list of recommended tracks
Note: Total seeds (artists + tracks + genres) must be between 1 and 5.
Use search_tracks to find seed track/artist IDs, or common genres like:
'pop', 'rock', 'hip-hop', 'electronic', 'jazz', 'classical', 'r-n-b', 'country' |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| create_mood_playlist | Create a playlist based on mood and preferences. |
| analyze_large_playlist | Analyze a large playlist efficiently using pagination. |
| discover_music_systematically | Systematically discover music using search pagination. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| current_user | Current user's profile. |
| current_playback_resource | Current playback state. |