2.0.5

A lightweight Model Context Protocol (MCP) server that enables AI assistants like Cursor & Claude to control Spotify playback and manage playlists.

Note: This version (2.0.x) has been updated to comply with Spotify's February 2026 API migration. The server now uses direct HTTP calls to the new Spotify API endpoints instead of the deprecated SDK.

Contents

• Quick Start
• Example Interactions
• Tools
  • Read Operations
  • Album Operations
  • Play / Create Operations
• Setup
  • Prerequisites
  • Creating a Spotify Developer Application
  • Configuration
  • Authentication
• Integrating with Claude Desktop, Cursor, and VsCode (Cline)

Quick Start

# 1. Create config directory and file
mkdir -p ~/.spotify-mcp
cat > ~/.spotify-mcp/config.json << 'EOF'
{
  "clientId": "YOUR_SPOTIFY_CLIENT_ID",
  "clientSecret": "YOUR_SPOTIFY_CLIENT_SECRET",
  "redirectUri": "http://127.0.0.1:8888/callback"
}
EOF

# 2. Authenticate with Spotify (opens browser)
npx @0xbarandiaran/spotify-mcp-server auth

# 3. Add to your Claude/Cursor config and restart

See Creating a Spotify Developer Application to get your Client ID and Secret.

Example Interactions

• "Play Elvis's first song"
• "Create a Taylor Swift / Slipknot fusion playlist"
• "Copy all the techno tracks from my workout playlist to my work playlist"
• "Turn the volume down a bit"

Tools

Read Operations

1. searchSpotify

   • Description: Search for tracks, albums, artists, or playlists on Spotify
   • Parameters:
     • query (string): The search term
     • type (string): Type of item to search for (track, album, artist, playlist)
     • limit (number, optional): Maximum number of results to return (1-10, max 10 due to API limits)
   • Returns: List of matching items with their IDs, names, and additional details
   • Example: searchSpotify("bohemian rhapsody", "track", 10)

2. getNowPlaying

   • Description: Get information about the currently playing track on Spotify, including device and volume info
   • Parameters: None
   • Returns: Object containing track name, artist, album, playback progress, duration, playback state, device info, volume, and shuffle/repeat status
   • Example: getNowPlaying()

3. getMyPlaylists

   • Description: Get a list of the current user's playlists on Spotify
   • Parameters:
     • limit (number, optional): Maximum number of playlists to return (default: 20)
     • offset (number, optional): Index of the first playlist to return (default: 0)
   • Returns: Array of playlists with their IDs, names, track counts, and public status
   • Example: getMyPlaylists(10, 0)

4. getPlaylistTracks

   • Description: Get a list of tracks in a specific Spotify playlist
   • Parameters:
     • playlistId (string): The Spotify ID of the playlist
     • limit (number, optional): Maximum number of tracks to return (default: 100)
     • offset (number, optional): Index of the first track to return (default: 0)
   • Returns: Array of tracks with their IDs, names, artists, album, duration, and added date
   • Example: getPlaylistTracks("37i9dQZEVXcJZyENOWUFo7")

5. getRecentlyPlayed

   • Description: Retrieves a list of recently played tracks from Spotify.
   • Parameters:
     • limit (number, optional): A number specifying the maximum number of tracks to return.
   • Returns: If tracks are found it returns a formatted list of recently played tracks else a message stating: "You don't have any recently played tracks on Spotify".
   • Example: getRecentlyPlayed({ limit: 10 })

6. getUsersSavedTracks

   • Description: Get a list of tracks saved in the user's "Liked Songs" library
   • Parameters:
     • limit (number, optional): Maximum number of tracks to return (1-50, default: 50)
     • offset (number, optional): Offset for pagination (0-based index, default: 0)
   • Returns: Formatted list of saved tracks with track names, artists, duration, track IDs, and when they were added to Liked Songs. Shows pagination info (e.g., "1-20 of 150").
   • Example: getUsersSavedTracks({ limit: 20, offset: 0 })

7. getQueue

   • Description: Get the currently playing track and upcoming items in the Spotify queue
   • Parameters:
     • limit (number, optional): Maximum number of upcoming items to show (1-50, default: 10)
   • Returns: Currently playing track and list of upcoming tracks in the queue
   • Example: getQueue({ limit: 20 })

8. getAvailableDevices

   • Description: Get information about the user's available Spotify Connect devices
   • Parameters: None
   • Returns: List of available devices with name, type, active status, volume, and device ID
   • Example: getAvailableDevices()

Play / Create Operations

1. playMusic

   • Description: Start playing a track, album, artist, or playlist on Spotify
   • Parameters:
     • uri (string, optional): Spotify URI of the item to play (overrides type and id)
     • type (string, optional): Type of item to play (track, album, artist, playlist)
     • id (string, optional): Spotify ID of the item to play
     • deviceId (string, optional): ID of the device to play on
   • Returns: Success status
   • Example: playMusic({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
   • Alternative: playMusic({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })

2. pausePlayback

   • Description: Pause the currently playing track on Spotify
   • Parameters:
     • deviceId (string, optional): ID of the device to pause
   • Returns: Success status
   • Example: pausePlayback()

3. resumePlayback

   • Description: Resume Spotify playback on the active device
   • Parameters:
     • deviceId (string, optional): ID of the device to resume playback on
   • Returns: Success status
   • Example: resumePlayback()

4. skipToNext

   • Description: Skip to the next track in the current playback queue
   • Parameters:
     • deviceId (string, optional): ID of the device
   • Returns: Success status
   • Example: skipToNext()

5. skipToPrevious

   • Description: Skip to the previous track in the current playback queue
   • Parameters:
     • deviceId (string, optional): ID of the device
   • Returns: Success status
   • Example: skipToPrevious()

6. createPlaylist

   • Description: Create a new playlist on Spotify
   • Parameters:
     • name (string): Name for the new playlist
     • description (string, optional): Description for the playlist
     • public (boolean, optional): Whether the playlist should be public (default: false)
   • Returns: Object with the new playlist's ID and URL
   • Example: createPlaylist({ name: "Workout Mix", description: "Songs to get pumped up", public: false })

7. addTracksToPlaylist

   • Description: Add tracks to an existing Spotify playlist
   • Parameters:
     • playlistId (string): ID of the playlist
     • trackUris (array): Array of track URIs or IDs to add
     • position (number, optional): Position to insert tracks
   • Returns: Success status and snapshot ID
   • Example: addTracksToPlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", trackUris: ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh"] })

8. addToQueue

   • Description: Adds a track, album, artist or playlist to the current playback queue
   • Parameters:
     • uri (string, optional): Spotify URI of the item to add to queue (overrides type and id)
     • type (string, optional): Type of item to queue (track, album, artist, playlist)
     • id (string, optional): Spotify ID of the item to queue
     • deviceId (string, optional): ID of the device to queue on
   • Returns: Success status
   • Example: addToQueue({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
   • Alternative: addToQueue({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })

9. setVolume

   • Description: Set the playback volume to a specific percentage (requires Spotify Premium)
   • Parameters:
     • volumePercent (number): The volume to set (0-100)
     • deviceId (string, optional): ID of the device to set volume on
   • Returns: Success status with the new volume level
   • Example: setVolume({ volumePercent: 50 })

10. adjustVolume

• Description: Adjust the playback volume up or down by a relative amount (requires Spotify Premium)
• Parameters:
  • adjustment (number): The amount to adjust volume by (-100 to 100). Positive values increase volume, negative values decrease it.
  • deviceId (string, optional): ID of the device to adjust volume on
• Returns: Success status showing the volume change (e.g., "Volume increased from 50% to 60%")
• Example: adjustVolume({ adjustment: 10 }) (increase by 10%)
• Example: adjustVolume({ adjustment: -20 }) (decrease by 20%)

Album Operations

1. getAlbums

   • Description: Get detailed information about one or more albums by their Spotify IDs
   • Parameters:
     • albumIds (string|array): A single album ID or array of album IDs (max 20)
   • Returns: Album details including name, artists, release date, type, total tracks, and ID. For single album returns detailed view, for multiple albums returns summary list.
   • Example: getAlbums("4aawyAB9vmqN3uQ7FjRGTy") or getAlbums(["4aawyAB9vmqN3uQ7FjRGTy", "1DFixLWuPkv3KT3TnV35m3"])

2. getAlbumTracks

   • Description: Get tracks from a specific album with pagination support
   • Parameters:
     • albumId (string): The Spotify ID of the album
     • limit (number, optional): Maximum number of tracks to return (1-50)
     • offset (number, optional): Offset for pagination (0-based index)
   • Returns: List of tracks from the album with track names, artists, duration, and IDs. Shows pagination info.
   • Example: getAlbumTracks("4aawyAB9vmqN3uQ7FjRGTy", 10, 0)

3. saveOrRemoveAlbumForUser

   • Description: Save or remove albums from the user's "Your Music" library
   • Parameters:
     • albumIds (array): Array of Spotify album IDs (max 20)
     • action (string): Action to perform: "save" or "remove"
   • Returns: Success status with confirmation message
   • Example: saveOrRemoveAlbumForUser(["4aawyAB9vmqN3uQ7FjRGTy"], "save")

4. checkUsersSavedAlbums

   • Description: Check if albums are saved in the user's "Your Music" library
   • Parameters:
     • albumIds (array): Array of Spotify album IDs to check (max 20)
   • Returns: Status of each album (saved or not saved)
   • Example: checkUsersSavedAlbums(["4aawyAB9vmqN3uQ7FjRGTy", "1DFixLWuPkv3KT3TnV35m3"])

Setup

Prerequisites

• Node.js v18+
• A Spotify Premium account (required for the app owner due to Spotify API changes)
• A registered Spotify Developer application

Important: As of February 2026, Spotify requires the app owner to maintain an active Spotify Premium subscription for Development Mode apps. The app will stop functioning if the Premium subscription lapses.

Creating a Spotify Developer Application

1. Go to the Spotify Developer Dashboard
2. Log in with your Spotify account
3. Click the "Create an App" button
4. Fill in the app name and description
5. Accept the Terms of Service and click "Create"
6. In your new app's dashboard, you'll see your Client ID
7. Click "Show Client Secret" to reveal your Client Secret
8. Click "Edit Settings" and add a Redirect URI: http://127.0.0.1:8888/callback
9. Save your changes

Configuration

The server looks for configuration in these locations (in order):

1. ~/.spotify-mcp/config.json (recommended for npx users)
2. ./spotify-config.json (current directory, for local development)

Create your config file:

# Create the config directory
mkdir -p ~/.spotify-mcp

# Create the config file
cat > ~/.spotify-mcp/config.json << 'EOF'
{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "redirectUri": "http://127.0.0.1:8888/callback"
}
EOF

Or if you prefer, edit ~/.spotify-mcp/config.json manually with your favorite editor.

Authentication

The Spotify API uses OAuth 2.0 for authentication. Run the authentication command:

# Using npx (recommended)
npx @0xbarandiaran/spotify-mcp-server auth

# Or if cloned locally
npm run auth

This will:

1. Open your browser to Spotify's authorization page
2. After you approve, capture the authorization code
3. Exchange it for access and refresh tokens
4. Save the tokens to your config file

Your config file will now include the tokens:

{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "redirectUri": "http://127.0.0.1:8888/callback",
  "accessToken": "BQAi9Pn...kKQ",
  "refreshToken": "AQDQcj...7w",
  "expiresAt": 1677889354671
}

Automatic Token Refresh: The server automatically refreshes the access token when it expires (typically after 1 hour). If refresh fails, run the auth command again.

Integrating with Claude Desktop, Cursor, and VsCode (Cline)

Claude Desktop / Claude Code

Add to your Claude configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@0xbarandiaran/spotify-mcp-server"]
    }
  }
}

Then restart Claude Desktop.

Cursor

Go to the MCP tab in Cursor Settings (command + shift + J). Add a server with this command:

npx -y @0xbarandiaran/spotify-mcp-server

Cline (VS Code Extension)

Add to your cline_mcp_settings.json:

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@0xbarandiaran/spotify-mcp-server"],
      "autoApprove": ["getNowPlaying", "getMyPlaylists", "searchSpotify"]
    }
  }
}

Development

Building from source

git clone https://github.com/gabrielbarandiaran/spotify-mcp-server.git
cd spotify-mcp-server
npm install
npm run build

Running locally

# Run the MCP server
node build/index.js

# Run authentication
node build/auth.js

License

MIT