spotify-mcp-server

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

Contents

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

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

2. getNowPlaying

3. getMyPlaylists

4. getPlaylistTracks

5. getRecentlyPlayed

6. getUsersSavedTracks

7. getQueue

8. getAvailableDevices

9. removeUsersSavedTracks

Play / Create Operations

1. playMusic

2. pausePlayback

3. resumePlayback

4. skipToNext

5. skipToPrevious

6. createPlaylist

7. addTracksToPlaylist

8. addToQueue

9. setVolume

10. adjustVolume

Album Operations

1. getAlbums

2. getAlbumTracks

3. saveOrRemoveAlbumForUser

4. checkUsersSavedAlbums

Playlist Operations

1. getPlaylist

2. updatePlaylist

3. removeTracksFromPlaylist

4. reorderPlaylistItems

Setup

Prerequisites

• Latest Node.js Current release (currently v26.8.1; older release lines are unsupported)
• 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 ci
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://127.0.0.1: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://127.0.0.1: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

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

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

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

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

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

Note: The `expiresAt` field is a Unix timestamp (in milliseconds) indicating when the access token expires.

7. Automatic Token Refresh: The server will automatically refresh the access token when it expires (typically after 1 hour). The refresh happens transparently using the `refreshToken`, so you don't need to re-authenticate manually. If the refresh fails, you'll need to run `npm run auth` again to re-authenticate.

Integrating with Claude Desktop, Cursor, and VsCode Via Cline model extension

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

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": ["~/../spotify-mcp-server/build/index.js"],
      "autoApprove": ["getListeningHistory", "getNowPlaying"]
    }
  }
}

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

Development

The server uses MCP TypeScript SDK v2 and Zod 4, serving protocol revision `2026-07-28` while retaining compatibility with legacy MCP clients. Only the latest Node.js Current release is supported (minimum v26.8.1). CI follows the latest Current release. Install the locked dependencies with `npm ci`.

npm run lint
npm run typecheck
npm test

Tests exercise MCP initialization, tool discovery, validation, and Spotify operations using mocked HTTP responses. They do not require Spotify credentials or change your Spotify account.