Documentation

Setup Guide

Get the Spotify MCP Server running in under 5 minutes.

1

Create a Spotify App

  1. Go to the Spotify Developer Dashboard
  2. Click Create App
  3. Set the Redirect URI to http://127.0.0.1:8888/callback
  4. Copy your Client ID (you don't need the client secret — we use PKCE)
2

Install the Server

Option A: Clone from GitHub

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

Option B: Install from npm

Terminal 
npm install -g spotify-mcp-server

Option C: Run directly with npx (no install)

Terminal 
npx spotify-mcp-server
3

Configure Environment

Terminal 
cp .env.example .env

Edit .env with your values:

.env 
SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback
TOKEN_ENCRYPTION_KEY=<generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))">
TOKEN_STORAGE_PATH=~/.spotify-mcp/tokens.enc
4

Add to Claude

Claude Code

Add to your project's .mcp.json or global ~/.claude.json:

.mcp.json 
{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/path/to/spotify-mcp-server/dist/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "TOKEN_ENCRYPTION_KEY": "your_64_char_hex_key",
        "TOKEN_STORAGE_PATH": "~/.spotify-mcp/tokens.enc"
      }
    }
  }
}

Claude Desktop

Open Settings → Developer → Edit Config and add to claude_desktop_config.json:

claude_desktop_config.json 
{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/absolute/path/to/spotify-mcp-server/dist/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "TOKEN_ENCRYPTION_KEY": "your_64_char_hex_key",
        "TOKEN_STORAGE_PATH": "/absolute/path/to/.spotify-mcp/tokens.enc"
      }
    }
  }
}
5

Authenticate & Create

Start Claude and ask it to create a playlist. On first use, it will open your browser for Spotify OAuth login. After authenticating, your tokens are encrypted and stored locally — you won't need to log in again unless you explicitly disconnect.

Claude 
"Make me a playlist of songs that feel like 3am in a diner —
lonely but not sad, warm coffee and neon lights"

Claude will search Spotify, create the playlist, and add tracks — all automatically.

Troubleshooting

OAuth callback isn't working

Make sure your Redirect URI in the Spotify Dashboard exactly matches http://127.0.0.1:8888/callback (not localhost). Port 8888 must be available on your machine.

Search returns no results

Spotify Dev Mode caps search to 10 results. Claude may need to try multiple queries with different phrasing. This is expected behavior in Dev Mode.

Token errors after restart

Ensure your TOKEN_ENCRYPTION_KEY hasn't changed. If it has, delete the token file and re-authenticate.