spotify-mcp

Spotify MCP Node Server

A Model Context Protocol (MCP) Node server that enables AI assistants like Claude Desktop, or IDEs like Cursor and Windsurf to control Spotify playback and manage playlists. Great for music discovery and creative playlist curation. Try asking Claude for some less-known tracks in a genre or similar to an artist. You can start by asking to create a new playlist or update an existing playlist.

For an easiest quickstart, as of May 2025 the Claude Desktop is the recommended way to use this software. Install Claude Desktop for your platform and follow the integration guide below.

To comply with Spotify’s Developer Terms, you must have a Spotify Premium account to use this server. Additionally, if you’re using MCP-enabled AI assistants (such as Claude) with this server, you must opt out of data sharing for model training.

Contents

• Example Interactions
• Tools
  • Read Operations
  • Play / Create Operations
• Setup
  • Prerequisites
  • Installation
  • Creating a Spotify Developer Application
  • Spotify API Configuration
  • Authentication Process
• Integrating with AI assistants

Example Interactions

• _"Play The Beatles less known bootlegs"_
• _"Make a fusion playlist of The Beatles and Metallica"_
• _"What are the audio features of the track 'Bohemian Rhapsody' by Queen?"_
• _"Create my marathon playlist and add tracks from my workout playlists"_

Tools

Read Operations

1. searchSpotify

2. getNowPlaying

3. getUserPlaylists

4. getPlaylistTracks

5. getRecentlyPlayed

6. getRecentlyPlayed

7. getFollowedArtists

8. getUserTopItems

Play / Create Operations

1. playMusic

2. pausePlayback

3. skipToNext

4. skipToPrevious

5. createPlaylist

6. addTracksToPlaylist

7. addToQueue

Setup

Prerequisites

• Installed Node.js
• A Spotify Premium account
• A registered Spotify Developer application

MCP Server Installation

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

Node.js Installation

1. Go to Node.js download page

2. Download an install a recent Node.js version for your platform

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 "Edit Settings" and add a Redirect URI (e.g., `http://127.0.0.1:8888/callback`)

8. Save your changes

Spotify API Configuration

Create a `spotify-config.json` file in the project root:

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

Then edit the file by adding your client id only. The `accessToken`, `refreshToken` and `accessTokenExpiresAt` will be managed automatically. The `redirectUri` should be the same as the one you added in the Spotify Developer Dashboard. `127.0.0.1` is the simplest option for the local MCP server.

{
  "clientId": "you-must-add-your-client-id-here",
  "redirectUri": "http://127.0.0.1:8888/callback",
  "accessToken": "your-access-token-filled-automatically",
  "refreshToken": "your-refresh-token-filled-automatically",
  "accessTokenExpiresAt": 0
}

Authentication Process

The Spotify API uses OAuth 2.0 with the PKCE extension for secure authentication. You do NOT need a client secret for this app.

1. Run the authentication script in the directory of the cloned repository:

npm run auth

2. The script will open your browser to the Spotify authorization page.

3. Log in to Spotify and authorize your application.

4. After authorization, Spotify will redirect you to your specified redirect URI. The app will automatically handle the code exchange and save your tokens.

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

6. These tokens will be saved to your `spotify-config.json` file.

{
  "clientId": "your-client-id",
  "redirectUri": "http://127.0.0.1:8888/callback",
  "accessToken": "your-access-token-filled-automatically",
  "refreshToken": "your-refresh-token-filled-automatically",
  "accessTokenExpiresAt": 0
}

7. The server will automatically refresh the access token when needed, so you don't need to re-authenticate.

Integrating with AI assistants

Claude Desktop

The easiest way to use the Spotify MCP server is with Claude Desktop. Start Claude Desktop installation and then locate the Claude configuration file, go to `Claude Settings`,click on `Developer` and then `Edit Config`. Add the following to the configuration with an absolute path to the server:

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

Cursor

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

node absolute/path/to/spotify-mcp/build/index.js

VsCode (via Cline)

To set up your MCP correctly with Cline ensure you have the following file configuration set `cline_mcp_settings.json`:

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/absolute/path/to/spotify-mcp/build/index.js"],
      "autoApprove": ["getListeningHistory", "getNowPlaying"]
    }
  }
}

You can add additional tools to the auto approval array to run the tools without intervention.

Windsurf

In `Settings` then `Windsurf Settings` type `MCP` in the search bar. In the results MCP section click `add server` and then `add custom server`. Add the following configuration:

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

You can add additional tools to the auto approval array to run the tools without intervention.

Credits

This project was inspired by spotify-mcp-server by Marcel Marais. Main modifications:

1. The authentication process was refactored to use the Spotify API’s PKCE extension, eliminating the need for local client secret storage and repeated re-authentication.

2. Added new tools to understand user's taste.