Merge Unified's Spotify integration Merge Agent Handler's Spotify MCP server

Connect your AI Agents to Spotify in minutes

Merge lets you securely connect your agents to Spotify and thousands of tools instantly

Start building for free

Read docs

Spotify

Learn more about Merge Agent Handler

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}.

View all tools by creating a free account See more tools

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}
11

Copy Code

Open 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}

Copy Code

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  }

Copy Code

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}

Copy Code

FAQs on using Merge's Spotify MCP server

Explore other MCP servers built and managed by Merge

ActiveCampaign

Adobe PDF Services

Ahrefs

Airtable

Amadeus

Amazon S3

Amplitude

Anaplan

Apollo

Arize

Articulate Reach 360

Asana

Attio

Aviationstack

BambooHR

Basecamp

Bitbucket

Bitly

Box

CMS Coverage

Calendly

Canva

ClickUp

ClinicalTrials.gov

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