spotify mcp server

Local 2025-08-31 23:52:06 0
Os Automation @marcelmarais/spotify-mcp-server

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

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

Contents - [Example Interactions](#example-interactions) - [Tools](#tools) - [Read Operations](#read-operations) - [Play / Create Operations](#play--create-operations) - [Setup](#setup) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Creating a Spotify Developer Application](#creating-a-spotify-developer-application) - [Spotify API Configuration](#spotify-api-configuration) - [Authentication Process](#authentication-process) - [Integrating with Claude Desktop and Cursor](#integrating-with-claude-desktop-and-cursor) -

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"

Tools

Read Operations

  1. searchSpotify

  2. Description: Search for tracks, albums, artists, or playlists on Spotify

  3. 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 (10-50)
  4. Returns: List of matching items with their IDs, names, and additional details

  5. Example: searchSpotify("bohemian rhapsody", "track", 20)

  6. getNowPlaying

  7. Description: Get information about the currently playing track on Spotify

  8. Parameters: None
  9. Returns: Object containing track name, artist, album, playback progress, duration, and playback state

  10. Example: getNowPlaying()

  11. getMyPlaylists

  12. Description: Get a list of the current User is playlists on Spotify

  13. Parameters:
    • limit (number, optional): Maximum number of playlists to return (default: 20)
    • offset (number, optional): Index of the first playlist to return (default: 0)
  14. Returns: Array of playlists with their IDs, names, track counts, and public status

  15. Example: getMyPlaylists(10, 0)

  16. getPlaylistTracks

  17. Description: Get a list of tracks in a specific Spotify playlist
  18. 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)
  19. Returns: Array of tracks with their IDs, names, artists, album, duration, and added date
  20. Example: getPlaylistTracks("37i9dQZEVXcJZyENOWUFo7")

Play / Create Operations

  1. playMusic

  2. Description: Start playing a track, album, artist, or playlist on Spotify

  3. 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
  4. Returns: Success status
  5. Example: playMusic({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })

  6. Alternative: playMusic({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })

  7. pausePlayback

  8. Description: Pause the currently playing track on Spotify

  9. Parameters:
    • deviceId (string, optional): ID of the device to pause
  10. Returns: Success status

  11. Example: pausePlayback()

  12. skipToNext

  13. Description: Skip to the next track in the current playback queue

  14. Parameters:
    • deviceId (string, optional): ID of the device
  15. Returns: Success status

  16. Example: skipToNext()

  17. skipToPrevious

  18. Description: Skip to the previous track in the current playback queue

  19. Parameters:
    • deviceId (string, optional): ID of the device
  20. Returns: Success status

  21. Example: skipToPrevious()

  22. createPlaylist

  23. Description: Create a new playlist on Spotify

  24. 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)
  25. Returns: Object with the new playlist's ID and URL

  26. Example: createPlaylist({ name: "Workout Mix", description: "Songs to get pumped up", public: false })

  27. addTracksToPlaylist

  28. Description: Add tracks to an existing Spotify playlist
  29. Parameters:
    • playlistId (string): ID of the playlist
    • trackUris (array): Array of track URIs or IDs to add
    • position (number, optional): Position to insert tracks
  30. Returns: Success status and snapshot ID

  31. Example: addTracksToPlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", trackUris: ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh"] })

  32. addToQueue

  33. 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
  35. Returns: Success status
  36. Example: addToQueue({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
  37. Alternative: addToQueue({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })

Setup

Prerequisites

  • Node.js v16+
  • A Spotify Premium account
  • A registered Spotify Developer application

Installation

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

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 (e.g., http://localhost:8888/callback)
  9. Save your changes

Spotify API Configuration

Create a spotify-config.json file in the project root (you can copy and modify the provided example):

# Copy the example config file
cp spotify-config.example.json spotify-config.json

Then edit the file with your credentials:

{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "redirectUri": "http://localhost:8888/callback"
}

Authentication Process

The Spotify API uses OAuth 2.0 for authentication. Follow these steps to authenticate your application:

  1. Run the authentication script:
npm run auth

  1. The script will generate an authorization URL. Open this URL in your web browser.

  2. You'll be prompted to log in to Spotify and authorize your application.

  3. After authorization, Spotify will redirect you to your specified redirect URI with a code parameter in the URL.

  4. The authentication script will automatically exchange this code for access and refresh tokens.

  5. These tokens will be saved to your spotify-config.json file, which will now look something like:

{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "redirectUri": "http://localhost:8888/callback",
  "accessToken": "BQAi9Pn...kKQ",
  "refreshToken": "AQDQcj...7w",
  "expiresAt": 1677889354671
}
  1. The server will automatically refresh the access token when needed, using the refresh token.

Integrating with Claude Desktop and Cursor

To use your MCP server with Claude Desktop, add it to your Claude configuration:

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["spotify-mcp-server/build/index.js"]
    }
  }
}

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

node path/to/spotify-mcp-server/build/index.js
[
  {
    "description": "Search for tracks, albums, artists, or playlists on Spotify",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "limit": {
          "description": "Maximum number of results to return (10-50)",
          "maximum": 50,
          "minimum": 1,
          "type": "number"
        },
        "query": {
          "description": "The search query",
          "type": "string"
        },
        "type": {
          "description": "The type of item to search for either track, album, artist, or playlist",
          "enum": [
            "track",
            "album",
            "artist",
            "playlist"
          ],
          "type": "string"
        }
      },
      "required": [
        "query",
        "type"
      ],
      "type": "object"
    },
    "name": "searchSpotify"
  },
  {
    "description": "Get information about the currently playing track on Spotify",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {},
      "type": "object"
    },
    "name": "getNowPlaying"
  },
  {
    "description": "Get a list of the current User is playlists on Spotify",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "limit": {
          "description": "Maximum number of playlists to return (1-50)",
          "maximum": 50,
          "minimum": 1,
          "type": "number"
        }
      },
      "type": "object"
    },
    "name": "getMyPlaylists"
  },
  {
    "description": "Get a list of tracks in a Spotify playlist",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "limit": {
          "description": "Maximum number of tracks to return (1-50)",
          "maximum": 50,
          "minimum": 1,
          "type": "number"
        },
        "playlistId": {
          "description": "The Spotify ID of the playlist",
          "type": "string"
        }
      },
      "required": [
        "playlistId"
      ],
      "type": "object"
    },
    "name": "getPlaylistTracks"
  },
  {
    "description": "Start playing a Spotify track, album, artist, or playlist",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "deviceId": {
          "description": "The Spotify device ID to play on",
          "type": "string"
        },
        "id": {
          "description": "The Spotify ID of the item to play",
          "type": "string"
        },
        "type": {
          "description": "The type of item to play",
          "enum": [
            "track",
            "album",
            "artist",
            "playlist"
          ],
          "type": "string"
        },
        "uri": {
          "description": "The Spotify URI to play (overrides type and id)",
          "type": "string"
        }
      },
      "type": "object"
    },
    "name": "playMusic"
  },
  {
    "description": "Pause Spotify playback on the active device",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "deviceId": {
          "description": "The Spotify device ID to pause playback on",
          "type": "string"
        }
      },
      "type": "object"
    },
    "name": "pausePlayback"
  },
  {
    "description": "Skip to the next track in the current Spotify playback queue",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "deviceId": {
          "description": "The Spotify device ID to skip on",
          "type": "string"
        }
      },
      "type": "object"
    },
    "name": "skipToNext"
  },
  {
    "description": "Skip to the previous track in the current Spotify playback queue",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "deviceId": {
          "description": "The Spotify device ID to skip on",
          "type": "string"
        }
      },
      "type": "object"
    },
    "name": "skipToPrevious"
  },
  {
    "description": "Create a new playlist on Spotify",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "description": {
          "description": "The description of the playlist",
          "type": "string"
        },
        "name": {
          "description": "The name of the playlist",
          "type": "string"
        },
        "public": {
          "description": "Whether the playlist should be public",
          "type": "boolean"
        }
      },
      "required": [
        "name"
      ],
      "type": "object"
    },
    "name": "createPlaylist"
  },
  {
    "description": "Add tracks to a Spotify playlist",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "playlistId": {
          "description": "The Spotify ID of the playlist",
          "type": "string"
        },
        "position": {
          "description": "Position to insert the tracks (0-based index)",
          "minimum": 0,
          "type": "number"
        },
        "trackIds": {
          "description": "Array of Spotify track IDs to add",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "playlistId",
        "trackIds"
      ],
      "type": "object"
    },
    "name": "addTracksToPlaylist"
  },
  {
    "description": "Resume Spotify playback on the active device",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "deviceId": {
          "description": "The Spotify device ID to resume playback on",
          "type": "string"
        }
      },
      "type": "object"
    },
    "name": "resumePlayback"
  },
  {
    "description": "Adds a track, album, artist or playlist to the playback queue",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "deviceId": {
          "description": "The Spotify device ID to add the track to",
          "type": "string"
        },
        "id": {
          "description": "The Spotify ID of the item to play",
          "type": "string"
        },
        "type": {
          "description": "The type of item to play",
          "enum": [
            "track",
            "album",
            "artist",
            "playlist"
          ],
          "type": "string"
        },
        "uri": {
          "description": "The Spotify URI to play (overrides type and id)",
          "type": "string"
        }
      },
      "type": "object"
    },
    "name": "addToQueue"
  }
]