Connect your AI Agents to Spotify in minutes

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.
validate_credential
Validate Spotify credentials by fetching the current user profile. Returns {success, message}.

How to set up Merge Agent Handler
In an mcp.json file, add the configuration below, and restart Cursor.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5 "headers": {
6 "Authorization": "Bearer yMt*****"
7 }
8 }
9 }
10}
11Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.
Make sure Claude is using the Node v20+.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "yMt*****"
14 }
15 }
16 }
17}Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "<ah-production-access-key>"
14 }
15 }
16 }
17 }In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".
You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.
Learn more in the official documentation ↗
1{
2 "inputs": [
3 {
4 "type": "promptString",
5 "id": "agent-handler-auth",
6 "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7 "password": true
8 }
9 ],
10 "servers": {
11 "agent-handler": {
12 "type": "stdio",
13 "command": "npx",
14 "args": [
15 "-y",
16 "mcp-remote@latest",
17 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18 "--header",
19 "Authorization: Bearer ${input:agent-handler-auth}"
20 ]
21 }
22 }
23}FAQs on using Merge's Spotify MCP server
FAQs on using Merge's Spotify MCP server
What is a Spotify MCP?
It's an MCP server that connects your agents to Spotify's music platform via tools. Your agents can invoke these tools to search for music, control playback, manage playlists, access listening history, and more.
Spotify doesn't offer an official MCP server, but you can use one from a third-party platform, like Merge Agent Handler.
How can I use the Spotify MCP server?
The use cases naturally depend on the agent you've built, but here are a few common ones:
- Mood-based playlist generation: When a user describes what they want to listen to in a chat interface, an agent searches Spotify for matching tracks, creates a new playlist, adds them to it, and starts playback on the user's active device
- Automatic workout playlist updates: When a user logs a workout in a fitness app, an agent checks the activity type, searches Spotify for tracks matching the right energy level, and adds new songs to the user's workout playlist to keep it fresh
- Weekly listening recap: On a Friday schedule, an agent pulls the user's top tracks and recently played history from Spotify, formats them into a digest, and sends the summary by Slack message or email
- Context-aware focus music: When a deep work session starts in a calendar or productivity tool, an agent begins a low-distraction playlist on the user's Spotify device and pauses playback automatically when the session ends
What are popular tools for Spotify's MCP server?
Here are some of the most commonly used tools:
search: searches Spotify for tracks, artists, albums, playlists, or podcasts matching a text query. Use this when an agent needs to find specific music content before adding it to a queue, playlist, or playback session
start_playback: begins or resumes playback on a specified device, optionally targeting a track, album, or playlist URI. Call this when an agent needs to trigger music in response to a user action or a scheduled workflow event
create_playlist: creates a new Spotify playlist for the current user with a name, description, and visibility setting. Use this when an agent is assembling a curated set of tracks and needs a destination to collect them
add_playlist_items: adds one or more tracks to an existing Spotify playlist by URI. Good for agents that build playlists incrementally from search results, user preferences, or external recommendation data
get_currently_playing: returns the track currently playing on the user's Spotify account, including track name, artist, and playback state. Helpful when an agent needs to check what's active before making a queue management or logging decision
get_user_top_items: returns the user's top tracks or artists over a short, medium, or long time range. Use this when an agent needs to personalize recommendations or generate a listening summary based on real listening behavior
What makes Merge Agent Handler's Spotify MCP server better than alternative Spotify MCP servers?
Spotify doesn't have an official MCP server, so if you're choosing between a community implementation and a managed platform, here's what differentiates Merge Agent Handler:
- Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For Spotify, this means you can prevent listening history, playlist contents, and user account details from being surfaced to agents that don't specifically need them
- Managed authentication and credentials: Merge stores and manages your Spotify OAuth credentials on your behalf. You never embed tokens in agent configuration or deal with re-authorization when they expire after the standard one-hour window
- Real-time observability and audit trail: Every tool call against Spotify is logged with timestamp, tool name, parameters, and response data. Teams building music-integrated products can audit exactly what an agent played, searched, or modified without any custom instrumentation
- Tool Packs and controlled access: Tool Packs let you bundle specific Spotify tools with tools from other connectors into a single MCP endpoint, scoped to a specific use case. An agent gets exactly the tools it needs, nothing more
How can I start using Merge Agent Handler's Spotify MCP server?
You can take the following steps:
1. Create or log into your Merge Agent Handler account and navigate to Tool Packs (collections of connector tools scoped to a specific use case).
2. Create a new Tool Pack, then find and enable the Spotify connector. Match tools to your use case. For example, use search and get_user_top_items for discovery and reporting, and use tools like start_playback, create_playlist, and add_playlist_items to control playback or manage music libraries.
3. Add a Registered User inside the Tool Pack. This is the identity context under which your agent operates. Merge generates a unique MCP URL scoped to this user once it's created.
4. From the Registered User detail page, authenticate Spotify by completing the OAuth flow. Merge stores and manages the credentials going forward.
5. Copy the MCP URL from the Tool Pack detail page and generate an API key from Settings. You'll need both to connect your agent.
6. Add the MCP server to your agent or IDE using the MCP URL and API key. Your Spotify tools are now accessible through that endpoint.
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now






















