🎧 Spotify MCP Server

A lightweight Model Context Protocol (MCP) server that lets AI assistants like Claude, Codex and Cursor control Spotify playback and manage your library and playlists.

About • Examples • Tools • Getting started • MCP clients • Credits

📖 About

This server exposes the Spotify Web API as 30 MCP tools, so an AI assistant can search the catalog, see what’s playing, control playback and volume, manage the queue and edit your playlists and library, all in natural language.

Based on marcelmarais/spotify-mcp-server. This version keeps the original implementation and adds:

• 🐳 a Docker-first workflow with Docker Compose

• ⚙️ configuration through a local .env file

• 🔑 persisted OAuth tokens in a mounted volume, with proactive refresh every 45 minutes

• 📊 extra tools: getTopTracks, getTopArtists and unfollowPlaylist

• 🤖 a setup that works out of the box with Codex, Claude and Cursor

Related MCP server: spotify-mcp-server

💬 Example prompts

• "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"

• "What have I been listening to the most this month?"

• "Turn the volume down a bit"

🧰 Tools

🚀 Getting started

Prerequisites

• Docker Desktop (recommended) or Node.js 20+

• A Spotify Premium account (required for playback controls)

• An app in the Spotify Developer Dashboard

1. Create a Spotify app

1. Open the Spotify Developer Dashboard and click Create app.

2. Add http://127.0.0.1:8888/callback as a Redirect URI.

3. Copy the app’s Client ID and Client Secret.

2. Run with Docker (recommended)

# Clone the repository
git clone https://github.com/agustinhopneto/spotify-mcp-server.git
cd spotify-mcp-server

# Create your .env and fill SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET
cp .env.example .env

# Build the image
npm run docker:build

# Authorize your Spotify account (opens the OAuth flow on port 8888)
npm run docker:auth

# Start the server in the background
npm run docker:up

Tokens are saved to data/spotify-config.json. Never commit or share this file. If Spotify revokes the token or the automatic refresh fails, run npm run docker:auth again.

Alternative: run with Node.js

npm install
cp spotify-config.example.json spotify-config.json  # add your clientId, clientSecret and redirectUri
npm run auth    # authorize your account; tokens are saved to spotify-config.json
npm run build

🔌 Connecting an MCP client

MCP talks over stdio, so the client starts one MCP process per connection.

With Docker: the process runs inside the persistent container. Run npm run docker:up first and replace the path with your own:

{
  "mcpServers": {
    "spotify": {
      "command": "docker",
      "args": [
        "compose", "-f", "/absolute/path/to/spotify-mcp-server/compose.yaml",
        "exec", "-T", "spotify-mcp", "node", "build/index.js"
      ]
    }
  }
}

With Node.js:

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

This configuration works with Claude Desktop, Codex, Cursor (Settings → MCP) and Cline (cline_mcp_settings.json).

🧱 Architecture

flowchart LR
    AI[AI assistant<br/><sub>Claude · Codex · Cursor</sub>] <-->|MCP over stdio| S[Spotify MCP Server]
    S -->|Spotify Web API SDK| SP[(Spotify)]
    S <--> T[(spotify-config.json<br/><sub>OAuth tokens</sub>)]

src/
├── index.ts     # MCP server bootstrap + token refresh
├── auth.ts      # OAuth authorization flow
├── read.ts      # Read tools
├── play.ts      # Playback tools
├── albums.ts    # Album tools
├── playlist.ts  # Playlist tools
├── utils.ts     # Spotify client, token handling, helpers
└── types.ts

🛠️ Development

CI runs lint and type checking on every push and pull request, and Dependabot keeps the dependencies up to date.

🙏 Credits

This project is based on marcelmarais/spotify-mcp-server. All credit for the original implementation goes to its author and contributors. ⭐ Go give the original a star!

Maintained with 💚 by Agustinho Neto