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

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

Tool	Description
spotify_search_track	Search tracks (query, optional limit 1–10)
spotify_play	Play a track URI on the active (or given) device
spotify_play_search	Search and play the best match
spotify_pause	Pause playback
spotify_resume	Resume playback
spotify_next	Skip to next track
spotify_previous	Go to previous track
spotify_add_to_queue	Queue a track URI
spotify_queue_search	Search and queue the best match
spotify_now_playing	Current track and progress
spotify_devices	List Spotify Connect devices
spotify_transfer	Transfer playback to another device
spotify_volume	Set volume 0–100%

Scripts

Command	Description
npm run auth	Browser OAuth login; writes .spotify-token.json
npm start	Start the MCP server on stdio
npm run inspect	Open the MCP Inspector against this server
npm run typecheck	Run TypeScript checks

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