spotify-mcp by sespinosa - MCP Server

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

Clone this repository
Install dependencies:
```
npm install
```
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

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

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

Use spotify_auth_url to generate an authorization URL with desired scopes
Direct user to the URL to authorize the app
After authorization, use spotify_exchange_code with the code and state from the callback
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:

Set the environment variable SPOTIFY_PERSIST_TOKENS=true
Tokens will be securely stored in your home directory (~/.spotify-mcp-tokens.json)
The server will automatically load saved tokens on startup
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