<div align="center">

<img src="https://upload.wikimedia.org/wikipedia/commons/8/84/Spotify_icon.svg" alt="Spotify" width="72" height="72" />

# 🎧 Spotify MCP Server

**A lightweight [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets AI assistants like Claude, Codex and Cursor control Spotify playback and manage your library and playlists.**

![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
![Node.js](https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-000000?style=for-the-badge&logo=modelcontextprotocol&logoColor=white)
![Spotify](https://img.shields.io/badge/Spotify_Web_API-1DB954?style=for-the-badge&logo=spotify&logoColor=white)
![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white)
![Biome](https://img.shields.io/badge/Biome-60A5FA?style=for-the-badge&logo=biome&logoColor=white)

[About](#-about) •
[Examples](#-example-prompts) •
[Tools](#-tools) •
[Getting started](#-getting-started) •
[MCP clients](#-connecting-an-mcp-client) •
[Credits](#-credits)

</div>

---

## 📖 About

This server exposes the [Spotify Web API](https://developer.spotify.com/documentation/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](https://github.com/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

## 💬 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

<details open>
<summary><b>🔎 Read</b></summary>

| Tool | Description |
|---|---|
| `searchSpotify` | Search for tracks, albums, artists or playlists |
| `getNowPlaying` | Current track, progress, device, volume and shuffle/repeat state |
| `getMyPlaylists` | The current user’s playlists |
| `getPlaylistTracks` | Tracks in a playlist |
| `getRecentlyPlayed` | Recently played tracks |
| `getUsersSavedTracks` | Tracks in "Liked Songs" (paginated) |
| `getTopTracks` | The user’s most-played tracks over a time range |
| `getTopArtists` | The user’s most-played artists over a time range |
| `getQueue` | Current track and upcoming items in the queue |
| `getAvailableDevices` | Available Spotify Connect devices |
| `removeUsersSavedTracks` | Remove tracks from "Liked Songs" (max 40) |

</details>

<details>
<summary><b>▶️ Playback</b></summary>

| Tool | Description |
|---|---|
| `playMusic` | Play a track, album, artist or playlist (by URI or type + ID) |
| `pausePlayback` | Pause playback |
| `resumePlayback` | Resume playback |
| `skipToNext` | Skip to the next track |
| `skipToPrevious` | Go back to the previous track |
| `addToQueue` | Add an item to the playback queue |
| `setVolume` | Set the volume to a percentage (Premium) |
| `adjustVolume` | Raise or lower the volume by a relative amount (Premium) |

</details>

<details>
<summary><b>💿 Albums</b></summary>

| Tool | Description |
|---|---|
| `getAlbums` | Details for one or more albums (max 20) |
| `getAlbumTracks` | Tracks from an album (paginated) |
| `saveOrRemoveAlbumForUser` | Save or remove albums from "Your Music" |
| `checkUsersSavedAlbums` | Check whether albums are saved in the library |

</details>

<details>
<summary><b>🎶 Playlists</b></summary>

| Tool | Description |
|---|---|
| `createPlaylist` | Create a new playlist |
| `getPlaylist` | Playlist details: owner, track count, visibility, description |
| `updatePlaylist` | Change name, description, public or collaborative settings |
| `addTracksToPlaylist` | Add tracks to a playlist |
| `removeTracksFromPlaylist` | Remove tracks from a playlist (max 100) |
| `reorderPlaylistItems` | Move a range of tracks to a new position |
| `unfollowPlaylist` | Remove a playlist from the user’s library |

</details>

## 🚀 Getting started

### Prerequisites

- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (recommended) or [Node.js](https://nodejs.org/) 20+
- A **Spotify Premium** account (required for playback controls)
- An app in the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/)

### 1. Create a Spotify app

1. Open the [Spotify Developer Dashboard](https://developer.spotify.com/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)

```bash
# 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.

| Command | Description |
|---|---|
| `npm run docker:build` | Build or update the image |
| `npm run docker:auth` | Connect your Spotify account in the browser |
| `npm run docker:up` | Start the container in the background |
| `npm run docker:logs` | Follow the container logs |
| `npm run docker:down` | Stop the container |

### Alternative: run with Node.js

```bash
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:

```json
{
  "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:**

```json
{
  "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

```mermaid
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

| Command | Description |
|---|---|
| `npm run build` | Compile TypeScript to `build/` |
| `npm run lint` | Lint with Biome |
| `npm run lint:fix` | Fix lint issues |
| `npm run typecheck` | Type check |

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](https://github.com/marcelmarais/spotify-mcp-server)**. All credit for the original implementation goes to its author and contributors. ⭐ Go give the original a star!

---

<div align="center">

Maintained with 💚 by **[Agustinho Neto](https://github.com/agustinhopneto)**

</div>