spotify-mcp

sespinosa/spotify-mcp

3.2

If you are the rightful owner of spotify-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

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

Tools
  1. spotify_auth_url

    Generate OAuth authorization URL

  2. spotify_exchange_code

    Exchange authorization code for tokens

  3. spotify_set_tokens

    Manually set access tokens

  4. spotify_refresh_token

    Refresh the access token

  5. spotify_search

    Search for content on Spotify

  6. spotify_get_track

    Get track details

  7. spotify_get_artist

    Get artist details

  8. spotify_get_album

    Get album details

  9. spotify_get_playlist

    Get playlist details

  10. spotify_play

    Start or resume playback

  11. spotify_pause

    Pause playback

  12. spotify_next

    Skip to next track

  13. spotify_previous

    Skip to previous track

  14. spotify_seek

    Seek to position in track

  15. spotify_set_volume

    Set playback volume

  16. spotify_get_playback_state

    Get current playback state

  17. spotify_get_devices

    Get available devices

  18. spotify_transfer_playback

    Transfer playback to another device

  19. spotify_toggle_shuffle

    Toggle shuffle mode

  20. spotify_set_repeat

    Set repeat mode

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:

  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