Server Configuration
Describes the environment variables required to run the server.
Name | Required | Description | Default |
---|---|---|---|
No arguments |
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 |
---|---|
get_album | Retrieve comprehensive information about a specific album from Spotify using its unique identifier. 🎯 USE CASES: • Check album details before adding to playlist • Get track listing for a specific album • View album artwork, release date, and artist information • Research album metadata for music discovery 📝 WHAT IT RETURNS: • Album name, artists, and release date • Complete track listing with durations • Album artwork in multiple resolutions • Spotify popularity metrics and genre information • External URLs and market availability 🔍 EXAMPLES: • "Get details for the album 'Abbey Road' by The Beatles" • "Show me information about album ID: 1klALx0u4AavZNEvC4LrTL" • "I need the track list for this album I found" ⚠️ REQUIREMENTS: • Valid Spotify access token with appropriate scopes • Album must exist and be available in user's market |
get_new_releases | Discover the latest album releases available on Spotify, perfect for staying up-to-date with new music. 🎯 USE CASES: • Weekly music discovery sessions • Finding new releases from favorite genres • Building "New Music Friday" playlists • Keeping up with trending releases in specific regions • Music blog content creation and curation 📝 WHAT IT RETURNS: • Recently released albums with release dates • Artist information and album artwork • Spotify popularity scores and listener counts • Genre classifications and market availability • External links and preview URLs where available 🔍 EXAMPLES: • "Show me the latest album releases this week" • "What new albums came out in the UK recently?" • "Find new releases, limit to 10 albums" • "I want to discover new music that just dropped" 💡 TIPS: • Use country parameter to get region-specific releases • Adjust limit based on how many discoveries you want • Perfect for automated weekly new music updates ⚠️ REQUIREMENTS: • Valid Spotify access token • Optional: Country code for region-specific results |
get_album_tracks | Retrieve the complete track listing for any album, including detailed information about each song. 🎯 USE CASES: • Building custom playlists from favorite albums • Checking track order and durations before purchase • Creating "deep cuts" playlists from lesser-known album tracks • Analyzing album structure and flow • Finding specific tracks within concept albums or compilations 📝 WHAT IT RETURNS: • Complete ordered track listing with track numbers • Individual track durations and preview URLs • Track popularity scores and explicit content flags • Artist credits for each track (including featured artists) • External IDs and market availability per track 🔍 EXAMPLES: • "Get all tracks from 'Dark Side of the Moon' album" • "Show me the tracklist for album ID: 4LH4d3cOWNNsVw41Gqt2kv" • "I want to see all songs from this compilation album" • "List the tracks from this soundtrack, limit to 20" 💡 TIPS: • Use this before adding entire albums to playlists • Great for discovering hidden gems in large albums • Check explicit flags if building family-friendly playlists ⚠️ REQUIREMENTS: • Valid Spotify access token • Album must be available in user's market |
search_albums | Search for albums using flexible keywords, artist names, or album titles to discover music. 🎯 USE CASES: • Finding albums when you only remember partial information • Discovering discographies of new artists • Searching for concept albums or themed collections • Finding albums by genre, mood, or era • Locating rare releases, deluxe editions, or remastered versions 📝 WHAT IT RETURNS: • Ranked search results based on relevance • Album names, artists, and release years • Album artwork and Spotify popularity metrics • Genre information and track counts • External URLs and availability information 🔍 EXAMPLES: • "Search for albums by 'Pink Floyd'" • "Find albums with 'greatest hits' in the title" • "Search for 'jazz piano' albums" • "Look for albums containing 'live' or 'concert'" • "Find albums released in '1969'" 💡 SEARCH TIPS: • Use quotes for exact phrase matching: "Abbey Road" • Combine artist and album names: "Beatles White Album" • Use genre keywords: "progressive rock", "indie folk" • Include year ranges: "1970s rock albums" • Try alternate spellings or abbreviations ⚠️ REQUIREMENTS: • Valid Spotify access token • Search query with meaningful keywords |
get_artist | Get comprehensive information about any artist including their biography, genres, and popularity metrics. 🎯 USE CASES: • Research artist background before concerts or festivals • Build artist-focused playlists with complete discography knowledge • Discover artist genres and influences for music recommendations • Analyze artist popularity trends and follower growth • Create detailed artist profiles for music databases 📝 WHAT IT RETURNS: • Artist name, biography, and profile images • Genre classifications and musical styles • Spotify popularity score and follower count • External URLs (official website, social media) • Related artist suggestions and collaborators 🔍 EXAMPLES: • "Get information about Taylor Swift" • "Show me details for artist ID: 06HL4z0CvFAxyc27GXpf02" • "I want to learn about this new artist I discovered" • "Get profile info for the band that sang this song" 💡 TIPS: • Use before exploring an artist's full catalog • Great for understanding an artist's evolution over time • Check follower count to gauge current popularity ⚠️ REQUIREMENTS: • Valid Spotify access token • Artist must exist in Spotify's database |
get_artist_albums | Explore an artist's complete discography including albums, singles, compilations, and appearances. 🎯 USE CASES: • Building complete artist discography playlists • Discovering rare releases and B-sides • Tracking artist evolution through their album releases • Finding collaborations and featured appearances • Creating chronological listening experiences 📝 WHAT IT RETURNS: • Complete album listing with release dates and types • Album artwork and track counts • Collaboration information and featured artists • Market availability and release formats • Popularity metrics for each release 🔍 EXAMPLES: • "Get all albums by The Beatles" • "Show me Drake's singles and EPs only" • "Find all releases by artist ID: 4dpARuHxo51G3z768sgnrY" • "I want to see Beyoncé's complete discography" 💡 ALBUM TYPES: • 'album' - Full studio albums • 'single' - Singles and EPs • 'compilation' - Greatest hits, compilations • 'appears_on' - Featured appearances on other artists' work ⚠️ REQUIREMENTS: • Valid Spotify access token • Artist must have releases available |
get_artist_top_tracks | Discover an artist's most popular and widely-played tracks based on global streaming data. 🎯 USE CASES: • Quick introduction to an artist's biggest hits • Building "best of" playlists for parties or events • Understanding which songs made an artist famous • Creating radio-friendly playlists with mainstream appeal • Checking what's trending from your favorite artists 📝 WHAT IT RETURNS: • Top 10 tracks ranked by global popularity • Track names, album information, and release dates • Popularity scores and play count estimates • Preview URLs and track durations • Market-specific popularity rankings 🔍 EXAMPLES: • "What are Ed Sheeran's top tracks?" • "Show me The Weeknd's biggest hits in the US" • "Get Ariana Grande's most popular songs" • "Find the top tracks for artist ID: 1Xyo4u8uXC1ZmMpatF05PJ" 🌍 MARKET SPECIFICITY: • Results can vary by country/region • Reflects local music preferences and cultural differences • Use country parameter for region-specific results • Defaults to US market if not specified ⚠️ REQUIREMENTS: • Valid Spotify access token • Artist must have released tracks |
search_artists | Search for artists using names, genres, or keywords to discover new music and talent. 🎯 USE CASES: • Finding artists when you only remember partial names • Discovering artists within specific genres or styles • Locating emerging or independent artists • Building diverse playlists with multiple artists • Researching artists for events or collaborations 📝 WHAT IT RETURNS: • Ranked artist results based on search relevance • Artist names, images, and genre classifications • Popularity scores and follower counts • Links to explore each artist's catalog • External URLs and social media links 🔍 EXAMPLES: • "Search for 'jazz pianist' artists" • "Find artists named 'John'" • "Look for 'indie rock' bands" • "Search for artists from 'Nashville'" • "Find 'female rapper' artists" 💡 SEARCH STRATEGIES: • Use genre keywords: "progressive metal", "folk acoustic" • Include location: "Seattle grunge", "Detroit techno" • Try instrument-specific searches: "saxophone", "violin" • Use descriptive terms: "soulful", "experimental", "classical" ⚠️ REQUIREMENTS: • Valid Spotify access token • Meaningful search keywords for best results |
get_followed_artists | Retrieve the complete list of artists that the user actively follows on Spotify. 🎯 USE CASES: • Managing your followed artists collection • Creating playlists from your favorite artists only • Checking for new releases from followed artists • Organizing your music library by preferred artists • Exporting your music taste profile for other platforms 📝 WHAT IT RETURNS: • Complete list of artists you follow • Artist names, images, and genre information • Follower counts and popularity metrics • Follow date and relationship duration • Quick access to each artist's catalog 🔍 EXAMPLES: • "Show me all artists I follow" • "Get my followed artists, limit to 50" • "Who are the artists in my following list?" • "Export my followed artists for playlist creation" 💡 MANAGEMENT TIPS: • Regularly review to unfollow inactive artists • Use this list to check for new releases • Great for creating "favorites only" playlists • Perfect for music taste analysis and statistics ⚠️ REQUIREMENTS: • Valid Spotify access token with user-follow-read scope • User must have followed at least one artist |
get_top_artists | Analyze your personal listening habits to discover your most played artists over different time periods. 🎯 USE CASES: • Understanding your personal music taste evolution • Creating "Year in Music" summaries and statistics • Building playlists based on your actual listening habits • Sharing your music taste with friends and social media • Discovering patterns in your music preferences 📝 WHAT IT RETURNS: • Your most listened-to artists ranked by play time • Artist names, images, and genre breakdowns • Listening statistics and time-period comparisons • Popularity scores and follower information • Insights into your musical preferences 🔍 EXAMPLES: • "Who are my top artists this month?" • "Show my most played artists of all time" • "Get my top 10 artists from the last 6 months" • "What artists have I been listening to most recently?" ⏰ TIME RANGES:
• 'short_term' - Last 4 weeks of listening
• 'medium_term' - Last 6 months of listening ⚠️ REQUIREMENTS: • Valid Spotify access token with user-top-read scope • Sufficient listening history for accurate results |
get_track | Retrieve comprehensive information about any specific track including detailed metadata and audio characteristics. 🎯 USE CASES: • Research song details for music blogs or articles • Analyze track metadata for music applications • Get complete song information for sharing or playlisting • Verify track details and availability before use • Build detailed music catalogs and databases 📝 WHAT IT RETURNS: • Complete track information (title, artist, album, duration) • Release date, popularity scores, and market availability • Track artwork, preview URLs, and external links • Explicit content flags and parental guidance information • ISRC codes and other professional identifiers 🔍 EXAMPLES: • "Get details for 'Hotel California' by Eagles" • "Show me information about track ID: 40riOy7x9W7GXjyGp4pjAv" • "I need complete details for this specific song" • "Get metadata for the track I just discovered" 💡 DETAILED INSIGHTS: • Professional music industry identifiers • Cross-platform compatibility information • Regional availability and licensing details • Perfect for music research and analysis • Essential for building music applications ⚠️ REQUIREMENTS: • Valid Spotify access token • Track must exist and be available in user's market |
search_tracks | Search specifically for individual tracks with targeted filtering for precise song discovery. 🎯 USE CASES: • Find specific songs when you remember lyrics or melodies • Discover tracks by particular artists or from specific albums • Build track-focused music discovery experiences • Find alternative versions, covers, or remixes of songs • Research song catalogs and discographies 📝 WHAT IT RETURNS: • Ranked track results based on search relevance • Song titles, artists, albums, and release information • Track popularity scores and listener engagement • Preview URLs for instant track sampling • Market availability and explicit content flags 🔍 EXAMPLES: • "Search for tracks with 'love' in the title" • "Find acoustic versions of popular songs" • "Look for instrumental jazz piano tracks" • "Search for covers of 'Yesterday' by The Beatles" 🎵 SEARCH PRECISION: • Track-specific results without album/artist clutter • Optimized for individual song discovery • Better for finding specific recordings or versions • Perfect for playlist building and curation • Ideal for karaoke or cover song searches 💡 SEARCH STRATEGIES: • Include specific lyrics: "lyrics hello darkness my old friend" • Search by genre: "indie folk acoustic guitar" • Find versions: "acoustic", "remix", "live", "cover" • Use artist filters: "artist:Taylor Swift love songs" • Include year ranges: "track:dancing year:2020-2023" ⚠️ REQUIREMENTS: • Valid Spotify access token • Search terms should be specific for best results |
get_liked_tracks | Access the user's personal collection of liked/saved tracks from their Spotify library. 🎯 USE CASES: • Display user's favorite music collection in applications • Create personalized playlists from liked songs • Analyze personal music taste and preferences • Build recommendation systems based on user favorites • Export personal music library for backup or migration 📝 WHAT IT RETURNS: • Complete collection of user's liked/saved tracks • Track information with save dates and timestamps • Artist, album, and release information for each track • Chronological order of when tracks were liked • Total count of saved tracks in library 🔍 EXAMPLES: • "Show me my liked songs collection" • "Get my 50 most recently liked tracks" • "What songs have I saved to my library?" • "Export my favorite tracks with save dates" 💖 PERSONAL COLLECTION: • Reflects user's musical taste and preferences • Shows evolution of music taste over time • Perfect for building "greatest hits" playlists • Useful for music discovery based on preferences • Great for sharing favorite music with friends 💡 COLLECTION INSIGHTS: • Track when musical tastes changed or evolved • Identify patterns in saved music genres • Use for personalized recommendation systems • Perfect for "throwback" and nostalgia playlists • Analyze your music journey over time ⚠️ REQUIREMENTS: • Valid Spotify access token with user-library-read scope • User must have saved tracks in their library |
save_tracks | Add tracks to the user's personal library, creating a permanent collection of favorite music. 🎯 USE CASES: • Save discovered tracks for future listening • Build personal music library from recommendations • Like tracks during music discovery sessions • Create permanent collections of favorite songs • Save music for offline listening and easy access 📝 WHAT IT RETURNS: • Confirmation of successful track saves • Updated library count and collection size • Timestamp information for when tracks were saved • Error details for tracks that couldn't be saved • Success status for bulk save operations 🔍 EXAMPLES: • "Save 'Bohemian Rhapsody' to my library" • "Add these 5 discovered tracks to my liked songs" • "Save track IDs: 4uLU6hMCjMI75M1A2tKUQC, 7qiZfU4dY1lWllzX7mkmht" • "Like all tracks from this great album" 💖 BUILDING YOUR COLLECTION: • Creates permanent access to favorite music • Tracks appear in your "Liked Songs" playlist • Enables offline playback for saved content • Perfect for building personalized music libraries • Essential for music discovery and curation 💡 COLLECTION STRATEGIES: • Save tracks immediately during discovery • Build thematic collections of related music • Use bulk saves for efficiency with multiple tracks • Regular saving helps track music evolution • Create personal "greatest hits" collections ⚠️ REQUIREMENTS: • Valid Spotify access token with user-library-modify scope • Tracks must be available in user's market • Maximum 50 tracks can be saved per request |
remove_tracks | Remove tracks from the user's personal library to maintain a curated collection of current favorites. 🎯 USE CASES: • Clean up library by removing tracks you no longer enjoy • Maintain relevance in your personal music collection • Remove accidental saves and unwanted additions • Update library to reflect changing musical tastes • Organize library by removing outdated preferences 📝 WHAT IT RETURNS: • Confirmation of successful track removals • Updated library count after removals • List of successfully removed tracks • Error details for tracks that couldn't be removed • Final library state after cleanup operation 🔍 EXAMPLES: • "Remove 'Old Song' from my liked tracks" • "Unlike these 3 tracks I no longer enjoy" • "Remove track IDs: 1BxfuPKGuaTgP6aM0NMpti, 4LRPiXqCikLlN15c3yImP7" • "Clean up my library by removing outdated music" 🧹 LIBRARY MAINTENANCE: • Keeps collection current and relevant • Reflects evolving musical tastes • Maintains quality over quantity approach • Perfect for regular library cleanup sessions • Essential for curated collection management 💡 CURATION TIPS: • Regular cleanup keeps library fresh • Remove tracks that no longer resonate • Consider seasonal relevance for cleanup timing • Use bulk removals for major library overhauls • Keep library aligned with current preferences ⚠️ REQUIREMENTS: • Valid Spotify access token with user-library-modify scope • Track IDs must match exactly for successful removal • Maximum 50 tracks can be removed per request |
get_top_tracks | Discover your most listened-to tracks based on actual listening history across different time periods. 🎯 USE CASES: • Understand your personal music listening patterns • Create "Year in Music" summaries and personal statistics • Build playlists based on your actual favorite songs • Share your top music with friends and social media • Track changes in musical preferences over time 📝 WHAT IT RETURNS: • Your most played tracks ranked by listening frequency • Track information with play count estimates • Time-period specific listening statistics • Artist and album information for top tracks • Insights into your musical preferences and habits 🔍 EXAMPLES: • "What are my top tracks this month?" • "Show my most listened songs of all time" • "Get my top 20 tracks from the last 6 months" • "What songs have I been playing on repeat recently?" ⏰ TIME PERIODS: • 'short_term' - Last 4 weeks of listening history • 'medium_term' - Last 6 months of musical activity • 'long_term' - All-time listening patterns and favorites • Compare across periods to see taste evolution 📊 LISTENING INSIGHTS: • Discover patterns in your music consumption • Identify your most-loved songs across different eras • Perfect for building "best of" personal playlists • Great for music discovery based on your actual preferences • Useful for understanding your musical identity 💡 PERSONAL ANALYTICS: • Track how your taste evolves over time • Identify seasonal listening patterns • Use for building recommendation systems • Share musical identity with others • Create data-driven personal playlists ⚠️ REQUIREMENTS: • Valid Spotify access token with user-top-read scope • Sufficient listening history for accurate results |
get_recently_played | Access your complete recent listening history with timestamps for tracking music activity and rediscovering songs. 🎯 USE CASES: • Track recent music discovery and listening habits • Rediscover songs you heard but forgot to save • Build "Recently Discovered" playlists from history • Monitor listening patterns and music consumption • Create activity logs for music journaling 📝 WHAT IT RETURNS: • Chronological list of recently played tracks • Exact timestamps of when each track was played • Track information including artist, album, and duration • Play context (playlist, album, or individual play) • Device information where tracks were played 🔍 EXAMPLES: • "What have I been listening to recently?" • "Show my last 50 played tracks with timestamps" • "What songs did I discover today?" • "Get my recent listening history for this week" ⏰ LISTENING HISTORY: • Shows exact sequence of recent music activity • Includes partial plays and skips • Perfect for rediscovering forgotten gems • Great for tracking music exploration sessions • Useful for building "recently discovered" collections 💡 HISTORY BENEFITS: • Never lose track of songs you enjoyed • Monitor listening habits and patterns • Perfect for building discovery-based playlists • Great for social sharing of recent finds • Essential for music tracking and journaling 🎵 REDISCOVERY OPPORTUNITIES: • Find songs you heard but didn't save • Track down music from specific listening sessions • Identify patterns in your music exploration • Perfect for playlist creation from recent activity ⚠️ REQUIREMENTS: • Valid Spotify access token with user-read-recently-played scope • History shows approximately last 50 tracks played |
get_track_lyrics | Retrieve plain text lyrics for any Spotify track in a clean, readable format. 🎯 USE CASES: • Analyze song lyrics for music analysis, research, or content creation • Display lyrics in music applications for reading along • Create lyric-based search and discovery features • Develop music education tools with lyric analysis • Build lyrics display features for music players 📝 WHAT IT RETURNS: • Structured response with success status and error handling • Complete track information (name, artist, album, duration) • Plain text lyrics in clean, readable format • Instrumental track detection for non-vocal content • Fallback message when lyrics are unavailable 🔍 EXAMPLES: • "Show me the lyrics for 'Bohemian Rhapsody' by Queen" • "Get the lyrics for this track" • "What are the lyrics to track ID: 4uLU6hMCjMI75M1A2tKUQC?" • "Display the song lyrics for analysis" 🎵 RESPONSE FORMAT: • Success response includes track metadata and lyrics string • Plain text lyrics with line breaks for easy reading • Error responses provide helpful fallback information • Instrumental flag indicates tracks without vocals • Clean format perfect for display and analysis 💡 LYRIC FEATURES: • Clean plain text format without timestamps • Easy to read and analyze lyrics content • Error handling for unavailable or missing lyrics • UTF-8 support for international character sets • Perfect for lyrics display and text analysis ⚠️ REQUIREMENTS: • Valid Spotify access token • Track must exist and be available in user's market • Uses external lyrics service for comprehensive coverage • Returns clean plain text lyrics only 🔍 EXAMPLE RESPONSE FORMAT: { "success": true, "track": { "name": "Bohemian Rhapsody", "artist": "Queen", "album": "A Night at the Opera", "duration": 354 }, "lyrics": "Verse 1: Is this the real life? Is this just fantasy? Caught in a landslide, No escape from reality. Chorus: Mama, just killed a man Put a gun against his head Pulled my trigger, now he's dead Verse 2: Too late, my time has come Sends shivers down my spine Body's aching all the time", "instrumental": false } |
get_playlist | Retrieve comprehensive information about any Spotify playlist including tracks, metadata, and creator details. 🎯 USE CASES: • Analyze playlist contents before following or copying • Check playlist length and total duration for events • View track listing to discover new music • Research playlist themes and genre consistency • Export playlist information for backup or sharing 📝 WHAT IT RETURNS: • Complete playlist metadata (name, description, creator) • Full track listing with artist and album information • Playlist artwork, follower count, and popularity metrics • Track order, durations, and explicit content flags • Public/private status and collaborative settings 🔍 EXAMPLES: • "Get details for Today's Top Hits playlist" • "Show me the tracks in playlist ID: 37i9dQZF1DXcBWIGoYBM5M" • "What songs are in my workout playlist?" • "Analyze this collaborative playlist my friends made" 💡 PLAYLIST INSIGHTS: • Perfect for playlist curation and discovery • Check before adding to your library • Great for party planning and event music selection • Useful for understanding music trends and preferences ⚠️ REQUIREMENTS: • Valid Spotify access token • Playlist must be public or user must have access |
get_user_playlists | Retrieve all playlists that the user owns, follows, or has access to in their Spotify library. 🎯 USE CASES: • Display user's complete playlist collection in applications • Create playlist management interfaces and organizers • Backup playlist metadata and track relationships • Build playlist analytics and listening habit insights • Implement playlist search and filtering systems 📝 WHAT IT RETURNS: • Complete list of user's playlists (owned and followed) • Playlist names, descriptions, and artwork • Creator information and follower counts • Track counts, durations, and last modification dates • Public/private status and collaborative permissions 🔍 EXAMPLES: • "Show me all my playlists" • "Get my playlist collection with 50 items" • "List all playlists I follow and created" • "What playlists do I have in my library?" 📊 PLAYLIST ORGANIZATION: • Includes both created and followed playlists • Shows ownership and collaboration status • Perfect for playlist management dashboards • Great for discovering forgotten playlists • Useful for library cleanup and organization 💡 MANAGEMENT TIPS: • Regular review helps maintain organized library • Check for duplicate or outdated playlists • Identify collaborative playlists for group management • Monitor follower growth on public playlists ⚠️ REQUIREMENTS: • Valid Spotify access token with playlist-read-private scope • User must have at least one playlist in their library |
get_playlist_tracks | Get the complete track listing from any playlist with detailed song information and metadata. 🎯 USE CASES: • Extract songs from playlists for custom music apps • Analyze musical patterns and genre distributions • Create backup copies or derivative playlists • Study playlist curation and track progression • Build recommendation systems based on playlist contents 📝 WHAT IT RETURNS: • Complete ordered track listing from the playlist • Song titles, artists, albums, and release dates • Track durations, popularity scores, and preview URLs • Added date and user who added each track • Explicit content flags and market availability 🔍 EXAMPLES: • "Get all tracks from my 'Road Trip' playlist" • "Show me songs in playlist ID: 1BxfuPKGuaTgP6aM0NMpti" • "List tracks from Spotify's RapCaviar playlist" • "Extract songs from this collaborative party playlist" 🎵 TRACK DETAILS: • Maintains original playlist order and context • Shows track addition history and contributors • Includes full metadata for each song • Perfect for playlist analysis and music research • Great for creating similar or inspired playlists 💡 ANALYSIS OPPORTUNITIES: • Genre distribution and musical diversity • Track popularity trends within playlists • Artist frequency and collaboration patterns • Temporal patterns in track additions ⚠️ REQUIREMENTS: • Valid Spotify access token • Playlist must be accessible to the user • Respect rate limits for large playlists |
create_playlist | Create a new custom playlist in the user's Spotify library with specified name and settings. 🎯 USE CASES: • Build themed playlists for specific moods or activities • Create event-specific music collections for parties • Organize music discoveries into curated collections • Build workout, study, or relaxation playlists • Create collaborative playlists for groups and friends 📝 WHAT IT RETURNS: • New playlist information with unique Spotify ID • Playlist URL for easy sharing and access • Creation confirmation with metadata • Empty playlist ready for track additions • Settings confirmation (public/private, collaborative) 🔍 EXAMPLES: • "Create a playlist called 'Summer Vibes 2024'" • "Make a private playlist for my workout music" • "Create 'Study Sessions' playlist with description" • "Build a collaborative playlist for our road trip" 🎵 PLAYLIST CUSTOMIZATION: • Custom name and description for context • Public or private visibility settings • Collaborative options for group contributions • Ready for immediate track additions • Perfect foundation for curated collections 💡 CREATION STRATEGIES: • Use descriptive names for easy discovery • Add detailed descriptions for context • Consider privacy settings based on content • Plan collaborative access for group playlists • Create multiple themed playlists for organization ⚠️ REQUIREMENTS: • Valid Spotify access token with playlist-modify-public/private scopes • Unique playlist name (duplicates allowed but not recommended) |
add_to_playlist | Add one or more tracks to any existing playlist that the user owns or can modify. 🎯 USE CASES: • Build and curate playlist collections with discovered music • Add recommended tracks from discovery algorithms • Collaborate on shared playlists with friends • Create themed collections by adding related songs • Maintain dynamic playlists that evolve with listening habits 📝 WHAT IT RETURNS: • Confirmation of successful track additions • Updated playlist length and total duration • New track positions within the playlist • Snapshot ID for tracking playlist changes • Error details for any tracks that couldn't be added 🔍 EXAMPLES: • "Add 'Bohemian Rhapsody' to my Rock Classics playlist" • "Put these 5 songs into my workout playlist" • "Add track spotify:track:4uLU6hMCjMI75M1A2tKUQC to favorites" • "Include all these discovered songs in my new releases list" 🎵 ADDITION FEATURES: • Add single tracks or multiple tracks at once • Tracks appear at the end of existing playlist • Maintains playlist order and structure • Supports bulk additions for efficiency • Perfect for playlist curation and growth 💡 CURATION TIPS: • Add tracks that fit the playlist theme or mood • Consider track flow and transitions • Test songs before adding to public playlists • Use bulk additions for efficiency • Regular playlist maintenance keeps content fresh ⚠️ REQUIREMENTS: • Valid Spotify access token with playlist-modify scopes • User must own playlist or have collaborative access • Tracks must be available in user's market |
remove_from_playlist | Remove unwanted tracks from any playlist that the user owns or can modify. 🎯 USE CASES: • Clean up playlists by removing outdated or unwanted songs • Maintain playlist quality by pruning poor matches • Remove duplicates and fix playlist organization • Update seasonal playlists by removing irrelevant tracks • Collaborate on playlist refinement with shared editing 📝 WHAT IT RETURNS: • Confirmation of successful track removals • Updated playlist length and duration • New snapshot ID reflecting the changes • List of successfully removed tracks • Error details for tracks that couldn't be removed 🔍 EXAMPLES: • "Remove 'Yesterday' from my Modern Hits playlist" • "Delete these 3 songs from my party playlist" • "Remove track spotify:track:4uLU6hMCjMI75M1A2tKUQC from favorites" • "Clean up duplicate songs from my road trip playlist" 🧹 CLEANING FEATURES: • Remove single tracks or multiple tracks at once • Maintains playlist integrity after removals • Preserves order of remaining tracks • Perfect for playlist maintenance and curation • Supports bulk removals for efficiency 💡 MAINTENANCE TIPS: • Regular cleanup keeps playlists relevant • Remove songs that no longer fit the theme • Check for duplicates and outdated content • Consider seasonal relevance for themed playlists • Use bulk removals for major playlist overhauls ⚠️ REQUIREMENTS: • Valid Spotify access token with playlist-modify scopes • User must own playlist or have collaborative access • Track URIs must match exactly for successful removal |
search_playlists | Search for public playlists using keywords, themes, or specific criteria to discover curated music collections. 🎯 USE CASES: • Discover playlists for specific moods, activities, or genres • Find curated music collections for events or occasions • Explore community-created playlists and music trends • Research popular playlist themes and curation styles • Find inspiration for creating your own playlist collections 📝 WHAT IT RETURNS: • Ranked playlist results based on search relevance • Playlist names, descriptions, and creator information • Follower counts, track counts, and playlist popularity • Playlist artwork and last modification dates • Links to explore and follow discovered playlists 🔍 EXAMPLES: • "Search for 'workout motivation' playlists" • "Find playlists with 'indie rock' in the title" • "Look for 'chill studying' playlist collections" • "Search for 'party music' playlists with many followers" 🔍 SEARCH STRATEGIES: • Use activity keywords: "running", "studying", "party" • Include genre terms: "jazz", "electronic", "country" • Try mood descriptors: "chill", "upbeat", "melancholy" • Combine terms: "indie folk acoustic", "90s hip hop" • Search for seasonal themes: "summer", "holiday", "spring" 💡 DISCOVERY BENEFITS: • Access to expertly curated music collections • Discover new artists through themed playlists • Find music for specific activities or moods • Learn about playlist curation and organization • Connect with music communities and trends ⚠️ REQUIREMENTS: • Valid Spotify access token • Results limited to public playlists only |
get_categories | Explore all available music categories that Spotify uses to organize and classify playlists and content. 🎯 USE CASES: • Build category-based music browsing interfaces • Discover music genres and style classifications • Create organized music discovery experiences • Research music categorization and taxonomy • Build genre-specific playlist recommendation systems 📝 WHAT IT RETURNS: • Complete list of Spotify's music categories • Category names, descriptions, and representative icons • Genre classifications and style groupings • Category popularity and playlist counts • Links to explore category-specific content 🔍 EXAMPLES: • "Show me all music categories on Spotify" • "Get browse categories for music discovery" • "What genres and categories are available?" • "List all music classification categories" 🗂️ CATEGORY TYPES: • Genre categories: Rock, Pop, Hip-Hop, Electronic, etc. • Mood categories: Chill, Party, Focus, Sleep, etc. • Activity categories: Workout, Commute, Gaming, etc. • Demographic categories: Kids, Decades, Regional, etc. • Special categories: New Releases, Charts, Discover, etc. 💡 ORGANIZATION BENEFITS: • Systematic approach to music discovery • Clear classification for different musical styles • Perfect for building browsing interfaces • Helps users navigate vast music catalogs • Professional categorization system 🎯 USE IN APPLICATIONS: • Create category-based navigation menus • Build genre-specific recommendation engines • Organize music content systematically • Provide structured music discovery experiences ⚠️ REQUIREMENTS: • Valid Spotify access token • Categories reflect current Spotify organization |
save_playlist | Save a user-created playlist to your Spotify library (follow playlist). 🎯 USE CASES: • Add user-created playlists to your library for offline access • Follow collaborative playlists from friends • Organize personal playlists into collections • Follow community-created playlists 📝 WHAT IT RETURNS: • Confirmation of successful playlist save/follow • Updated library status • Playlist URL for easy sharing and access • Error details for any failed saves 🔍 EXAMPLES: • "Save this collaborative playlist my friend created" • "Follow this user-generated workout playlist" • "Add this personal playlist to my library" 💡 SAVE FEATURES: • Works with user-created playlists • Maintains playlist order and structure • Perfect for following collaborative playlists • Enables offline access to followed playlists 🚫 LIMITATIONS (as of November 27, 2024): • Cannot save Spotify's official/editorial playlists • Cannot follow algorithmic playlists (Discover Weekly, etc.) • Only works with playlists created by users • Spotify-owned playlists are restricted 🔧 TROUBLESHOOTING: • If you get 404 error: The playlist might be Spotify-owned • Try with user-created playlists instead • Check if playlist is public and accessible ⚠️ REQUIREMENTS: • Valid Spotify access token with playlist-modify-public scope • Playlist must be user-created (not Spotify-owned) • Playlist must be public or accessible to your account |
unsave_playlist | Remove a user-created playlist from your Spotify library (unfollow playlist). 🎯 USE CASES: • Clean up library by unfollowing user-created playlists • Unfollow collaborative playlists that no longer match preferences • Remove personal playlist follows • Organize library by removing temporary follows 📝 WHAT IT RETURNS: • Confirmation of successful playlist unfollow • Updated library status • Status of the removal operation • Error details for any failed removals 🔍 EXAMPLES: • "Unfollow this user-created playlist" • "Remove this collaborative playlist from my library" • "Stop following this personal playlist" 💡 REMOVAL FEATURES: • Instantly unfollows playlist from your library • Doesn't delete the original playlist • You can re-follow the playlist anytime • Perfect for library maintenance 🚫 LIMITATIONS (as of November 27, 2024): • Cannot unfollow Spotify's official/editorial playlists • Cannot affect algorithmic playlists (they auto-appear) • Only works with user-created playlists you follow • Spotify-owned playlists are restricted 🔧 TROUBLESHOOTING: • If you get 404 error: The playlist might be Spotify-owned • Ensure you're currently following the playlist • Only works with user-created playlists 💡 MANAGEMENT TIPS: • Regular cleanup helps keep library organized • Unfollow playlists you no longer listen to • Consider creating your own versions of favorites • Use this for managing collaborative playlist follows ⚠️ REQUIREMENTS: • Valid Spotify access token with playlist-modify-public scope • Playlist must be user-created (not Spotify-owned) • You must currently be following the playlist |
get_currently_playing | Get real-time information about what's currently playing in the user's Spotify session. 🎯 USE CASES: • Display "Now Playing" information in applications • Track listening history and habits in real-time • Create social media posts about current music • Build music discovery features based on current listening • Monitor playback state for automation and smart home integration 📝 WHAT IT RETURNS: • Currently playing track with artist and album information • Playback progress (current position vs. total duration) • Playback state (playing, paused, stopped) • Active device information and volume level • Shuffle and repeat mode settings • Track popularity and explicit content flags 🔍 EXAMPLES: • "What song is currently playing?" • "Show me my current playback status" • "Get the current track and how much time is left" • "What device am I listening on right now?" 💡 REAL-TIME FEATURES: • Updates instantly as tracks change • Shows exact playback position down to milliseconds • Indicates if user is actively listening or paused • Perfect for building live music widgets ⚠️ REQUIREMENTS: • Valid Spotify access token with user-read-playback-state scope • User must have an active Spotify session |
start_playback | Initiate music playback with specific tracks, albums, playlists, or artist collections. 🎯 USE CASES: • Start playing music when users enter smart spaces • Create voice-activated music requests • Build custom music controllers and interfaces • Implement mood-based automatic music selection • Start themed playlists for events, workouts, or activities 📝 WHAT IT RETURNS: • Confirmation of playback initiation • Current track information and playback state • Device information where playback started • Error details if playback couldn't start • Queue information showing what will play next 🔍 EXAMPLES: • "Play my Discover Weekly playlist" • "Start playing the album 'Abbey Road'" • "Play tracks by The Beatles on my laptop" • "Begin playback of my liked songs" 🎵 PLAYBACK OPTIONS: • contextUri: Play entire albums, playlists, or artist catalogs • trackUris: Play specific individual tracks in order • deviceId: Choose which device should start playing • Can resume from where you left off or start fresh ⚠️ REQUIREMENTS: • Valid Spotify access token with user-modify-playback-state scope • User must have an active Spotify device available • Content must be available in user's market |
resume_player | Resume paused playback or continue playing from where the user left off. 🎯 USE CASES: • Resume music after phone calls or interruptions • Continue playback when returning to apps or devices • Implement "play/pause" toggle functionality • Resume listening after switching between devices • Restore playback state in smart home automations 📝 WHAT IT RETURNS: • Confirmation of resumed playback • Current track and position information • Updated playback state showing active play • Device information where playback resumed • Remaining track duration and queue preview 🔍 EXAMPLES: • "Resume my music where I left off" • "Continue playing on my phone" • "Resume the playlist I was listening to" • "Start playing again on my smart speaker" 💡 SMART RESUME: • Picks up exactly where playback was paused • Maintains queue order and shuffle settings • Preserves repeat mode and volume level • Can resume on the same or different device ⚠️ REQUIREMENTS: • Valid Spotify access token with user-modify-playback-state scope • Previous playback session must exist to resume • Target device must be available and active |
pause_player | Pause the current music playback while maintaining position and queue state. 🎯 USE CASES: • Pause music during calls, meetings, or conversations • Create automatic pause triggers for smart home systems • Implement voice commands for hands-free control • Pause playback when leaving designated areas • Build custom music control interfaces with pause functionality 📝 WHAT IT RETURNS: • Confirmation of successful pause operation • Final playback position before pausing • Current track information preserved for resume • Device state showing paused status • Queue information maintained for later resume 🔍 EXAMPLES: • "Pause my music" • "Stop playing on my bedroom speaker" • "Pause the current track" • "Hold the music for a moment" 💡 PAUSE BENEFITS: • Preserves exact playback position for seamless resume • Maintains queue, shuffle, and repeat settings • Keeps track information available for display • Allows for quick resume without losing context ⚠️ REQUIREMENTS: • Valid Spotify access token with user-modify-playback-state scope • Active playback session must be running • User must have appropriate device permissions |
skip_to_next | Skip to the next track in the user's playback queue or playlist. 🎯 USE CASES: • Skip songs that don't match current mood or activity • Navigate through playlists and albums quickly • Build custom music control interfaces • Create voice-activated skip commands • Implement automatic skipping based on user preferences 📝 WHAT IT RETURNS: • Information about the new track that started playing • Updated playback position reset to beginning • Queue information showing remaining tracks • Confirmation of successful skip operation • Device state with new playback status 🔍 EXAMPLES: • "Skip to the next song" • "Play the next track in this playlist" • "Move forward to the next song" • "I don't like this song, skip it" 🎵 SKIP BEHAVIOR: • Follows playlist/album order when not shuffled • Respects shuffle mode for random progression • May trigger repeat behavior at end of playlists • Updates listening history and statistics • Can trigger discovery algorithms for similar music ⚠️ REQUIREMENTS: • Valid Spotify access token with user-modify-playback-state scope • Active playback session with available next track • User must have appropriate device control permissions |
skip_to_previous | Skip to the previous track or restart the current track from the beginning. 🎯 USE CASES: • Go back to replay favorite parts of songs • Navigate backwards through playlists or albums • Correct accidental skips to next track • Replay tracks that were particularly enjoyable • Build comprehensive playback control systems 📝 WHAT IT RETURNS: • Information about the track that started playing • Playback position reset to beginning of track • Updated queue and playback state information • Confirmation of successful skip operation • Device status with new playback details 🔍 EXAMPLES: • "Go back to the previous song" • "Play that last track again" • "Skip back to the song before this one" • "I want to hear that again" 🎵 SKIP BEHAVIOR: • Restarts current track if more than 3 seconds have played • Goes to actual previous track if within first 3 seconds • Follows reverse playlist/album order • Respects shuffle mode for random navigation • Updates position in listening history ⚠️ REQUIREMENTS: • Valid Spotify access token with user-modify-playback-state scope • Active playback session currently running • Previous track must exist in queue or history |
set_volume | Adjust the volume level for the user's active Spotify device. 🎯 USE CASES: • Create dynamic volume adjustments for different times of day • Build smart home automation with volume control • Implement voice commands for hands-free volume changes • Adjust volume based on ambient noise levels • Create custom audio experience controls 📝 WHAT IT RETURNS: • Confirmation of successful volume change • Current volume level after adjustment • Device information showing updated state • Previous volume level for potential undo functionality • Playback state with new volume settings 🔍 EXAMPLES: • "Set volume to 50%" • "Lower the volume to 25" • "Turn up the music to 80%" • "Make it quieter, set to 15%" 🔊 VOLUME CONTROL: • Range: 0-100 percent • 0 = Complete silence (muted) • 100 = Maximum device volume • Changes apply instantly during playback • Preserves volume setting for future sessions ⚠️ REQUIREMENTS: • Valid Spotify access token with user-modify-playback-state scope • Active device that supports volume control • Device must be currently available and responsive |
add_to_queue | Add a specific track to the user's playback queue for immediate or upcoming playback. 🎯 USE CASES: • Queue up requested songs during parties or events • Build dynamic playlists on-the-fly based on mood • Add discovery tracks without interrupting current playlist • Create collaborative queuing for shared listening sessions • Implement "play this next" functionality 📝 WHAT IT RETURNS: • Confirmation that track was added to queue • Position of track in the upcoming queue • Estimated time until track will play • Current queue length and upcoming tracks preview • Track information that was successfully queued 🔍 EXAMPLES: • "Add 'Bohemian Rhapsody' to my queue" • "Queue up the track spotify:track:4uLU6hMCjMI75M1A2tKUQC" • "Add this song to play next" • "Put 'Sweet Child O Mine' in my queue" 🎵 QUEUE BEHAVIOR: • Tracks play in the order they were added • Queue plays after current track/playlist ends • Maintains queue across device switches • Can add multiple tracks for extended queuing • Integrates with existing shuffle and repeat settings ⚠️ REQUIREMENTS: • Valid Spotify access token with user-modify-playback-state scope • Track must be available in user's market • Active playback session or available device required |
get_devices | Retrieve all available Spotify-connected devices for the user's account. 🎯 USE CASES: • Display device options for playback targeting • Build device management and control interfaces • Check which devices are currently online and available • Monitor device battery levels and connection status • Create smart home integrations with Spotify-enabled devices 📝 WHAT IT RETURNS: • Complete list of user's connected devices • Device names, types, and unique identifiers • Current active state and availability status • Volume levels and playback capabilities • Device restrictions and supported features 🔍 EXAMPLES: • "Show me all my Spotify devices" • "What devices can I play music on?" • "List my available speakers and phones" • "Which devices are currently online?" 🔧 DEVICE TYPES: • Computer (desktop/laptop applications) • Smartphone (mobile apps) • Speaker (smart speakers, soundbars) • TV (smart TVs, streaming devices) • Car (automotive systems) • Game Console (PlayStation, Xbox) 💡 DEVICE MANAGEMENT: • Shows real-time availability status • Indicates which device is currently active • Displays volume control capabilities • Shows device-specific restrictions • Perfect for building device selector UIs ⚠️ REQUIREMENTS: • Valid Spotify access token with user-read-playback-state scope • At least one Spotify-enabled device must be logged in |
transfer_playback | Seamlessly transfer active playback from one device to another while maintaining playback state. 🎯 USE CASES: • Move music from phone to home speakers when arriving home • Switch from desktop to phone when leaving office • Transfer playback to car system when starting drive • Move music between rooms using different smart speakers • Continue listening on different devices without interruption 📝 WHAT IT RETURNS: • Confirmation of successful transfer • New active device information • Preserved playback position and queue • Current track information on new device • Transfer success status and any error details 🔍 EXAMPLES: • "Transfer playback to my bedroom speaker" • "Move music to my phone" • "Switch playback to device ID: 1a2b3c4d5e6f" • "Continue playing on my laptop" 🔄 TRANSFER FEATURES: • Maintains exact playback position • Preserves queue, shuffle, and repeat settings • Keeps volume level appropriate for target device • Option to start playing immediately or stay paused • Seamless transition with minimal interruption 💡 SMART HANDOFFS: • Perfect for multi-room audio setups • Enables mobility without losing music context • Great for smart home automation scenarios • Supports lifestyle-based listening patterns ⚠️ REQUIREMENTS: • Valid Spotify access token with user-modify-playback-state scope • Target device must be available and online • User must have control permissions for target device |
get_user_profile | Retrieve comprehensive information about the current Spotify user's profile, preferences, and account details. 🎯 USE CASES: • Display user information in music applications and dashboards • Personalize music experiences based on user demographics • Verify user identity and account status for features • Build user profiles for music recommendation systems • Create personalized greetings and user interfaces 📝 WHAT IT RETURNS: • User display name, real name, and profile images • Country/market information for content availability • Follower count and public profile statistics • Account type (free, premium) and subscription status • External URLs and social media links • User preferences and privacy settings 🔍 EXAMPLES: • "Show me my Spotify profile information" • "Get my account details and subscription status" • "What's my display name and profile picture?" • "Check my country setting and follower count" 👤 PROFILE INSIGHTS: • Essential for personalizing user experiences • Helps tailor content and recommendations • Useful for subscription-based feature access • Perfect for building user identity systems • Great for social features and sharing 💡 PERSONALIZATION OPPORTUNITIES: • Customize interfaces based on user preferences • Adjust content recommendations by market/country • Display appropriate subscription features • Build social connections using profile information • Create personalized music discovery experiences 🔒 PRIVACY CONSIDERATIONS: • Respects user privacy settings and preferences • Shows only publicly available information • Account for different privacy levels across users • Some information may be limited based on settings ⚠️ REQUIREMENTS: • Valid Spotify access token with user-read-private scope • User must have an active Spotify account |
search_music | Perform comprehensive music search across all Spotify content types with intelligent filtering and ranking. 🎯 USE CASES: • Universal music discovery across tracks, albums, artists, and playlists • Build intelligent search interfaces for music applications • Find specific songs when you only remember partial information • Discover new music based on keywords, moods, or themes • Create dynamic search-based music recommendations 📝 WHAT IT RETURNS: • Multi-type search results (tracks, artists, albums, playlists) • Relevance-ranked results based on Spotify's search algorithms • Complete metadata for each result type • Popularity scores and user engagement metrics • Links to explore each result in detail 🔍 EXAMPLES: • "Search for 'upbeat dance music' in tracks" • "Find 'acoustic guitar' content across all types" • "Look for 'Beatles' in artists and albums" • "Search for '90s hip hop' in playlists" 🎵 SEARCH TYPES: • 'track' - Individual songs and recordings • 'album' - Full album releases and EPs • 'artist' - Musicians, bands, and performers • 'playlist' - User and editorial playlists • 'show' - Podcasts and audio shows • 'episode' - Individual podcast episodes 💡 SEARCH STRATEGIES: • Use descriptive keywords: "chill indie folk" • Include artist names: "Taylor Swift love songs" • Try genre combinations: "electronic jazz fusion" • Use mood descriptors: "energetic workout beats" • Include decades: "80s synthwave nostalgia" 🔍 ADVANCED FEATURES: • Intelligent typo correction and suggestions • Context-aware search ranking • Market-specific availability filtering • Real-time search result updates • Multi-language search support ⚠️ REQUIREMENTS: • Valid Spotify access token • Search queries should be at least 2 characters long |
search_and_play_music | Instantly search for a track and begin playback in one seamless operation for immediate music gratification. 🎯 USE CASES: • Voice-activated music requests with instant playback • Quick music access without browsing interfaces • Party DJ functionality with instant song requests • Smart home integration with spoken music commands • Emergency music solutions when you need a specific song now 📝 WHAT IT RETURNS: • Search results showing the track that was found • Playback confirmation with current track information • Device information where playback started • Error details if track couldn't be found or played • Alternative suggestions if exact match isn't available 🔍 EXAMPLES: • "Search and play 'Bohemian Rhapsody' by Queen" • "Find and start 'Uptown Funk' immediately" • "Play the first result for 'relaxing piano music'" • "Search 'workout motivation' and start playing" 🎵 SMART PLAYBACK: • Automatically selects the best match from search results • Prioritizes popular and high-quality versions • Starts playback on user's active device • Falls back gracefully if preferred version unavailable • Maintains context for follow-up requests 💡 WORKFLOW OPTIMIZATION: • Eliminates manual track selection step • Perfect for hands-free music control • Reduces interaction friction for immediate needs • Great for mood-based music requests • Ideal for social settings and parties 🚀 INSTANT GRATIFICATION: • No browsing or selection required • Immediate musical response to requests • Perfect for time-sensitive music needs • Streamlined user experience • Ideal for voice and automation interfaces ⚠️ REQUIREMENTS: • Valid Spotify access token with user-modify-playback-state scope • Active Spotify device must be available • Search query should be specific enough for good matching |