> This page is for Agent Handler. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Spotify **Authentication:** OAuth. See [Magic Link](/merge-agent-handler/features/magic-link) for the runtime auth flow, or [Application credentials](/merge-agent-handler/admin-setup/add-oauth-credentials) to bring your own OAuth app. ## Sample use cases * Build a focus playlist of 50 ambient tracks I haven't heard before. * Find every song saved in the last 30 days that was added to a friend's playlist. * Pull my top 50 most-played tracks from the last 6 months. ## Available Tools #### get\_album Get details for a Spotify album by ID. Returns album name, artists, tracks, release date, genres, and more. #### list\_album\_tracks List tracks in a Spotify album with pagination. Use offset from page\_info to fetch next page. #### get\_artist Get details for a Spotify artist by ID. Returns name, genres, popularity, followers, and images. #### list\_artist\_albums List albums by a Spotify artist with pagination. Filter by include\_groups (album, single, appears\_on, compilation). #### get\_audiobook Get details for a Spotify audiobook by ID. Returns name, authors, narrators, publisher, chapters, and more. #### list\_audiobook\_chapters List chapters of a Spotify audiobook with pagination. Use offset from page\_info for next page. #### get\_chapter Get details for a Spotify audiobook chapter by ID. Returns name, description, duration, chapter number, and more. #### get\_episode Get details for a Spotify episode by ID. Returns name, description, duration, release date, show info, and more. #### follow Follow artists or users on Spotify. Provide type ('artist' or 'user') and list of Spotify IDs. #### unfollow Unfollow artists or users on Spotify. Provide type ('artist' or 'user') and list of Spotify IDs. #### list\_followed\_artists List artists the user follows. Cursor-based pagination: use 'after' from page\_info.cursor for next page. #### list\_saved\_tracks List the current user's saved tracks with pagination. Use offset from page\_info for next page. #### list\_saved\_albums List the current user's saved albums with pagination. Use offset from page\_info for next page. #### list\_saved\_shows List the current user's saved shows/podcasts with pagination. Use offset from page\_info for next page. #### list\_saved\_episodes List the current user's saved episodes with pagination. Use offset from page\_info for next page. #### list\_saved\_audiobooks List the current user's saved audiobooks with pagination. Use offset from page\_info for next page. #### save\_to\_library Save tracks, albums, shows, episodes, or audiobooks to the user's library. Provide type and list of IDs (max 50). #### remove\_from\_library Remove tracks, albums, shows, episodes, or audiobooks from the user's library. Provide type and list of IDs. #### check\_library Check if tracks, albums, shows, episodes, or audiobooks are saved in the user's library. Returns \{id, is\_saved} for each. #### get\_playback\_state Get the current playback state including device, repeat/shuffle mode, playing item, and progress. #### get\_devices Get the user's available Spotify devices. Returns device ID, name, type, volume, and active status. #### get\_currently\_playing Get the currently playing track or episode. Returns None if nothing is playing. #### get\_user\_queue Get the user's playback queue. Returns the currently playing item and upcoming items in the queue. #### start\_playback Start or resume playback. Requires Spotify Premium. Provide context\_uri (album/playlist) or uris (track list). Use get\_devices to find device\_id. #### pause\_playback Pause playback on the active device. Requires Spotify Premium. Use get\_devices to find device\_id. #### skip\_next Skip to the next track. Requires Spotify Premium. #### skip\_previous Skip to the previous track. Requires Spotify Premium. #### seek Seek to a position in the current track. Requires Spotify Premium. Position is in milliseconds. #### set\_repeat Set repeat mode: 'track' (repeat current), 'context' (repeat album/playlist), or 'off'. Requires Premium. #### set\_shuffle Enable or disable shuffle mode. Requires Spotify Premium. #### set\_volume Set playback volume (0-100). Requires Spotify Premium. Not available on all devices. #### add\_to\_queue Add a track or episode to the playback queue. Requires Premium. URI format: spotify:track:ID or spotify:episode:ID. #### transfer\_playback Transfer playback to another device. Requires Premium. Use get\_devices to find device IDs. Pass single device\_id in list. #### get\_playlist Get details for a Spotify playlist by ID. Returns name, description, owner, tracks, and images. #### list\_user\_playlists List the current user's playlists with pagination. Use offset from page\_info for next page. #### create\_playlist Create a new playlist for the current user. Returns the created playlist with ID and URI. #### update\_playlist Update a playlist's name, description, or visibility. Use get\_playlist to verify changes. #### list\_playlist\_items List items (tracks/episodes) in a playlist with pagination. Use offset from page\_info for next page. #### add\_playlist\_items Add tracks/episodes to a playlist. Provide URIs in spotify:track:ID or spotify:episode:ID format. Returns snapshot\_id. #### remove\_playlist\_items Remove tracks/episodes from a playlist by URI. Provide URIs in spotify:track:ID format. Returns snapshot\_id. #### reorder\_playlist\_items Reorder items in a playlist. Move range\_length items starting at range\_start to insert\_before position. #### search Search Spotify for tracks, albums, artists, playlists, shows, episodes, or audiobooks. Specify types as comma-separated string. Supports field filters like artist:name, album:name. #### get\_show Get details for a Spotify show/podcast by ID. Returns name, description, publisher, total episodes, and more. #### list\_show\_episodes List episodes of a Spotify show/podcast with pagination. Use offset from page\_info for next page. #### get\_track Get details for a Spotify track by ID. Returns track name, artists, album, duration, popularity, and more. #### get\_current\_user Get the current user's Spotify profile. Returns display name, email, country, subscription level, and more. #### get\_user\_top\_items Get the user's top artists or tracks based on listening history. Supports time ranges: short\_term (\~4 weeks), medium\_term (\~6 months), long\_term (all time). #### get\_recently\_played Get the user's recently played tracks. Cursor-based: use 'after' timestamp from page\_info.cursor for next page.