Spotify MCP

Model Context Protocol (MCP) server for Spotify. Let AI agents like Cursor, Claude Code, and Codex search tracks and control playback through the Spotify Web API.

Features

• Search tracks by title, artist, or natural language

• Play, pause, resume, skip, and go previous

• Search-and-play / search-and-queue in one step

• Read what’s currently playing

• List Spotify Connect devices and transfer playback

• Set volume (0–100%)

• OAuth login with automatic token refresh

Related MCP server: Spotify MCP Server

Requirements

• Node.js 18+

• A Spotify Premium account (playback control requires Premium)

• A Spotify Developer app (Dashboard)

Quick start

1. Clone and install

git clone https://github.com/AndreaZero/spotify-mcp.git
cd spotify-mcp
npm install

2. Create a Spotify app

1. Open the Spotify Developer Dashboard.

2. Create an app.

3. Under Redirect URIs, add:

   http://127.0.0.1:8888/callback

4. Copy the Client ID and Client Secret.

3. Configure environment

cp .env.example .env

Edit .env:

SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback

4. Authenticate

npm run auth

Open the printed URL in your browser, approve access, then wait until you see Spotify authentication successful. Tokens are saved to .spotify-token.json (gitignored) and refreshed automatically.

5. Run

npm start

Cursor setup

Add the server to your MCP config (e.g. ~/.cursor/mcp.json or project .cursor/mcp.json):

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/absolute/path/to/spotify-mcp",
      "env": {
        "SPOTIFY_CLIENT_ID": "your_spotify_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_spotify_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback"
      }
    }
  }
}

On Windows, use a full path for cwd, for example:

C:\\Users\\you\\Documents\\cursor-projects\\spotify-mcp

You can omit env if credentials already live in the project .env and the process starts with that working directory.

After saving, restart Cursor (or reload MCP servers), then try:

Play Everlong by Foo Fighters

What’s playing right now?

Set volume to 30

Claude Desktop / other MCP clients

Same idea: run npx tsx src/index.ts with cwd set to this repo and the Spotify env vars available.

Tools

Scripts

Project layout

spotify-mcp/
├── src/
│   ├── index.ts      # MCP server & tools
│   ├── auth.ts       # OAuth authorization flow
│   └── spotify.ts    # Spotify Web API client + token refresh
├── .env.example
├── package.json
└── tsconfig.json

OAuth scopes

The auth flow requests:

• user-read-playback-state

• user-read-currently-playing

• user-modify-playback-state

For a longer walkthrough, see docs/SETUP.md.

Troubleshooting

“Spotify not authenticated”
Run npm run auth again from the project root.

“No active device” / playback errors
Open Spotify on a phone, desktop, or web player so a Connect device is available, then call spotify_devices or spotify_transfer.

Redirect URI mismatch
The URI in the Dashboard must match SPOTIFY_REDIRECT_URI exactly (default http://127.0.0.1:8888/callback).

Token expired
Refresh is automatic when a refresh token exists. If refresh fails, delete .spotify-token.json and run npm run auth again.

Security

• Do not commit .env or .spotify-token.json.

• Keep your Client Secret private.

• See SECURITY.md for reporting issues.

Contributing

See CONTRIBUTING.md.

License

MIT