MCP HubMCP Hub
marcelmarais

spotify-mcp-server

by: marcelmarais

spotify mcp server

44created 19/03/2025
Visit
spotify
music

📌Overview

Purpose: To provide a lightweight Model Context Protocol (MCP) server that allows AI assistants like Cursor and Claude to control Spotify playback and manage playlists efficiently.

Overview: The Spotify MCP Server facilitates seamless integration between AI applications and Spotify, enabling users to control music playback and organize playlists through intuitive commands. This server acts as a bridge, allowing various interactions with Spotify’s features using the MCP framework.

Key Features:

  • Search Operations: Users can search for tracks, albums, artists, or playlists directly in Spotify using commands like searchSpotify, which returns detailed information based on specified parameters.

  • Playback Control: Commands such as playMusic, pausePlayback, and skipToNext allow for real-time control of music playback, enabling a smooth user experience tailored to personal preferences.

  • Playlist Management: Users can manage their Spotify playlists efficiently with features like createPlaylist for creating new playlists and addTracksToPlaylist for adding songs to existing playlists.

  • Current Playback Information: The getNowPlaying command provides users with information about the currently playing track, enhancing situational awareness during playback.

  • User-Friendly Setup: The server is easy to set up with clear installation instructions, prerequisites, and configuration steps to connect with Spotify's API, making it accessible to developers.

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
    • Play / Create 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"

Tools

Read Operations

  1. searchSpotify
    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): Max results (10-50)
    • Returns: List of matching items with IDs, names, etc.
    • Example: searchSpotify("bohemian rhapsody", "track", 20)

  2. getNowPlaying
    Get info about the currently playing track.

    • Parameters: None
    • Returns: Track name, artist, album, playback progress, duration, and state
    • Example: getNowPlaying()

  3. getMyPlaylists
    Get current user's playlists.

    • Parameters:
      • limit (number, optional, default 20)
      • offset (number, optional, default 0)
    • Returns: Array of playlists with IDs, names, counts, public status
    • Example: getMyPlaylists(10, 0)

  4. getPlaylistTracks
    Get tracks in a specific playlist.

    • Parameters:
      • playlistId (string)
      • limit (number, optional, default 100)
      • offset (number, optional, default 0)
    • Returns: Array of tracks with details
    • Example: getPlaylistTracks("37i9dQZEVXcJZyENOWUFo7")

  5. getRecentlyPlayed
    Retrieves recently played tracks.

    • Parameters:
      • limit (number, optional)
    • Returns: Formatted list of recently played tracks or message if none found
    • Example: getRecentlyPlayed({ limit: 10 })

Play / Create Operations

  1. playMusic
    Start playing a track, album, artist, or playlist.

    • Parameters:
      • uri (string, optional)
      • type (string, optional)
      • id (string, optional)
      • deviceId (string, optional)
    • Returns: Success status
    • Example: playMusic({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
    • Alternative: playMusic({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })

  2. pausePlayback
    Pause currently playing track.

    • Parameters:
      • deviceId (string, optional)
    • Returns: Success status
    • Example: pausePlayback()

  3. skipToNext
    Skip to the next track.

    • Parameters:
      • deviceId (string, optional)
    • Returns: Success status
    • Example: skipToNext()

  4. skipToPrevious
    Skip to the previous track.

    • Parameters:
      • deviceId (string, optional)
    • Returns: Success status
    • Example: skipToPrevious()

  5. createPlaylist
    Create a new playlist.

    • Parameters:
      • name (string)
      • description (string, optional)
      • public (boolean, optional, default false)
    • Returns: Object with new playlist's ID and URL
    • Example: createPlaylist({ name: "Workout Mix", description: "Songs to get pumped up", public: false })

  6. addTracksToPlaylist
    Add tracks to an existing playlist.

    • Parameters:
      • playlistId (string)
      • trackUris (array)
      • position (number, optional)
    • Returns: Success status and snapshot ID
    • Example: addTracksToPlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", trackUris: ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh"] })

  7. addToQueue
    Add a track, album, artist or playlist to the playback queue.

    • Parameters:
      • uri (string, optional)
      • type (string, optional)
      • id (string, optional)
      • deviceId (string, optional)
    • Returns: Success status
    • Example: addToQueue({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
    • 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: https://developer.spotify.com/dashboard/
  2. Log in with your Spotify account
  3. Click "Create an App"
  4. Fill in the app name and description
  5. Accept Terms of Service and click "Create"
  6. Get your Client ID and Client Secret
  7. Add a Redirect URI (e.g., http://localhost:8888/callback) in app settings

Spotify API Configuration

Copy the example config file and edit with your credentials:

cp spotify-config.example.json spotify-config.json

Example spotify-config.json:

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

Authentication Process

Spotify uses OAuth 2.0. To authenticate:

  1. Run:
npm run auth
  1. Open the generated authorization URL in your browser.
  2. Log in and authorize your app.
  3. After redirect, the script exchanges code for access and refresh tokens.
  4. Tokens saved in spotify-config.json:
{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "redirectUri": "http://localhost:8888/callback",
  "accessToken": "BQAi9Pn...kKQ",
  "refreshToken": "AQDQcj...7w",
  "expiresAt": 1677889354671
}
  1. The server auto-refreshes tokens when needed.

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

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

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

For Cursor:

  • Open MCP tab in Cursor Settings (command + shift + J)
  • Add a server with the command:
node path/to/spotify-mcp-server/build/index.js

For Cline, configure cline_mcp_settings.json:

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

Add additional tools to autoApprove to enable automatic tool execution.