> This page is for Workforce. > 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.