Spotify MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with the Spotify Web API.

Features

• Authentication: OAuth 2.0 with PKCE support
• Search: Search for tracks, artists, albums, and playlists
• Playback Control: Play, pause, skip, seek, volume control, and more
• Content Retrieval: Get detailed information about tracks, artists, albums, and playlists

Setup

1. Clone this repository

2. Install dependencies:

   npm install
   

3. Create a Spotify App:

   • Go to https://developer.spotify.com/dashboard
   • Create a new app
   • Add http://127.0.0.1:8888/callback to the Redirect URIs (or http://localhost:8888/callback)
   • Copy your Client ID and Client Secret

4. Set up environment variables:

   cp .env.example .env
   

   Edit .env and add your Spotify credentials:

   SPOTIFY_CLIENT_ID=your_client_id_here
   SPOTIFY_CLIENT_SECRET=your_client_secret_here
   SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback
   SPOTIFY_PERSIST_TOKENS=false
   

5. Build the project:

   npm run build
   

Usage

Running the Server

npm start

For development with auto-reload:

npm run dev

Available Tools

Authentication Tools

• spotify_auth_url: Generate OAuth authorization URL
• spotify_exchange_code: Exchange authorization code for tokens
• spotify_set_tokens: Manually set access tokens
• spotify_refresh_token: Refresh the access token

Search Tools

• spotify_search: Search for content on Spotify
  • Parameters: query, type (track/artist/album/playlist), limit

Content Tools

• spotify_get_track: Get track details
• spotify_get_artist: Get artist details
• spotify_get_album: Get album details
• spotify_get_playlist: Get playlist details

Playback Control Tools

• spotify_play: Start or resume playback
• spotify_pause: Pause playback
• spotify_next: Skip to next track
• spotify_previous: Skip to previous track
• spotify_seek: Seek to position in track
• spotify_set_volume: Set playback volume
• spotify_get_playback_state: Get current playback state
• spotify_get_devices: Get available devices
• spotify_transfer_playback: Transfer playback to another device
• spotify_toggle_shuffle: Toggle shuffle mode
• spotify_set_repeat: Set repeat mode (track/context/off)

Authentication Flow

1. Use spotify_auth_url to generate an authorization URL with desired scopes
2. Direct user to the URL to authorize the app
3. After authorization, use spotify_exchange_code with the code and state from the callback
4. The server will automatically manage token refresh when needed

Important for WSL Users: The callback URL (http://127.0.0.1:8888/callback) won't automatically open in WSL. After authorizing in your browser, you'll be redirected to a URL that may not load. Copy the entire URL from your browser's address bar and paste it back to the LLM to complete the authentication process.

Token Persistence

By default, authentication tokens are stored only in memory and will be lost when the server restarts. To enable persistent token storage:

1. Set the environment variable SPOTIFY_PERSIST_TOKENS=true
2. Tokens will be securely stored in your home directory (~/.spotify-mcp-tokens.json)
3. The server will automatically load saved tokens on startup
4. Tokens are saved with proper file permissions (readable only by the owner)

Security Note: Tokens are stored in plaintext in your home directory. Only enable persistence if you trust the security of your system.

Example Usage with Claude Desktop

Add the server to your Claude Desktop configuration:

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/path/to/spotify-mcp/dist/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "SPOTIFY_PERSIST_TOKENS": "false"
      }
    }
  }
}

Configuration with Claude CLI

When using Claude CLI, configure the MCP server with the built JavaScript file:

claude mcp add spotify node /path/to/spotify-mcp/dist/index.js

Important: Make sure to use the compiled JavaScript file from the dist/ directory, not the TypeScript source. The server requires Node.js to run and will automatically load environment variables from the .env file in the project root.

Required Scopes

Different features require different OAuth scopes:

• Basic search and content retrieval: No user scopes needed (uses Client Credentials)
• Playback control: user-modify-playback-state, user-read-playback-state
• User profile: user-read-private, user-read-email
• Library access: user-library-read, user-library-modify
• Playlist management: playlist-read-private, playlist-modify-public, playlist-modify-private

Development

Project Structure

spotify-mcp/
├── src/
│   ├── index.ts          # Main server implementation
│   ├── auth.ts           # OAuth authentication logic
│   └── playback-tools.ts # Playback control tools
├── dist/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Testing

The server uses stdio transport for communication with MCP clients. You can test it using any MCP-compatible client.

License

ISC