Spotify MCP Server

How to use

Connect an MCP client to the server to search tracks, albums, artists, and playlists; read the current player status and available devices; control playback (play, pause, skip, seek, volume, shuffle, repeat, queue); transfer playback between devices; manage playlists (create, update, add/remove items, reorder); and manage your saved tracks in the library. You will typically start by checking the current state, then issue batched commands to perform actions across multiple items. Every response includes a readable message that confirms what succeeded or failed.

How to install

Prerequisites: you need a JavaScript runtime. The project can run with Node.js or Bun. Follow the steps below to set up and run the server locally.

cd spotify-mcp
bun install

Create a local environment file from the example and configure your Spotify and OAuth details.

cp .env.example .env

Edit the environment file with your actual values. The following variables are used to connect to Spotify and control the OAuth flow. Replace placeholders with real values from your Spotify developer credentials.

PORT=3000
AUTH_ENABLED=true

# From https://developer.spotify.com/dashboard
SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret

# OAuth
OAUTH_SCOPES=playlist-read-private playlist-read-collaborative playlist-modify-public playlist-modify-private user-read-playback-state user-modify-playback-state user-read-currently-playing user-library-read user-library-modify
OAUTH_REDIRECT_URI=alice://oauth/callback
OAUTH_REDIRECT_ALLOWLIST=alice://oauth/callback

If you need to configure the Spotify dashboard, add redirect URIs for local testing and your app as shown in the run instructions.

Additional configuration and security notes

The HTTP transport and OAuth wrapper included for convenience are intended for local development. For remote deployments, harden the OAuth/HTTP layer with proper token validation, TLS termination, strict CORS/origin checks, rate limiting, and audit logging to stay compliant with Spotify terms.

Code and runtime support include a dual runtime that works with Node.js or Bun, and a Cloudflare Workers deployment path with KV storage for tokens. The server stores tokens securely and validates inputs to ensure robust operation across multiple users and devices.

Troubleshooting

If you see a device not found error, use the exact device_id value from the status output rather than a device name. If you encounter a no active device error, open Spotify on a device and verify the device list from the status command. When you hit an unauthorized error, complete the OAuth flow and refresh tokens as needed. If rate limits appear, wait briefly and retry.

HTTP Endpoints

The MCP exposes an HTTP interface for programmatic control and a separate OAuth flow for secure access. Use the endpoints to interact with the server and authorize clients.

Client configuration (Claude Desktop)

Configure your client to point at the MCP server so it can send batched actions to search, control playback, and manage playlists and library.

{
  "mcpServers": {
    "spotify": {
      "command": "bunx",
      "args": ["mcp-remote", "http://127.0.0.1:3000/mcp", "--transport", "http-only"],
      "env": { "NO_PROXY": "127.0.0.1,localhost" }
    }
  }
}

Cloudflare Workers

If you deploy to Cloudflare Workers, follow the built-in steps to create a KV namespace for token storage and to set the necessary environment variables. This enables scalable, serverless MCP operation with secure token handling.

Development

During development you can run the project with hot reloading, perform type checks, linting, and a production-oriented build and start.

bun dev           # Start with hot reload
bun run typecheck # TypeScript check
bun run lint      # Lint code
bun run build     # Production build
bun start         # Run production

Architecture

The server is organized into shared tools for Spotify interactions, OAuth flow handling, and storage, plus services that wrap Spotify API clients. This structure supports a clean separation between search, playback control, playlist management, and library operations.

Example session overview

A complete walkthrough demonstrates how to check what is playing, inspect available devices, select a playlist, start playback at a specific position, save a track to your library, and adjust the volume.

search_catalog

Find songs, artists, albums, or playlists based on search terms and types; supports batching to minimize API calls.

player_status

Return current player state, active devices, queue, and the currently playing track to inform control decisions.

spotify_control

Execute batch playback controls such as play, pause, next, previous, seek, volume, shuffle, repeat, transfer, and queue management.

spotify_playlist

Manage playlists including listing, getting details, creating, updating, adding/removing items, and reordering.

spotify_library

Manage saved tracks: list, add, remove, and check containment.