Spotify MCP Server

Model Context Protocol (MCP) server that provides Spotify integration for Claude Desktop.

⚠️ This project is experimental / for personal use only

This repository is a personal project created for fun and learning. It has not been exhaustively tested or production hardened. Use at your own risk — including re-authenticating if scopes change and backing up any important data.

Features

🔍 Search

• Search for tracks, albums, artists, and playlists

🎵 Playback Control

• Get current playback state

• Play/pause, skip, previous track

• Control volume and shuffle

• Seek within tracks

📚 Library Management

• Get saved tracks

• Save and remove tracks from library

• Check if tracks are saved

🎼 Playlists

• Get user playlists

• Create new playlists

• Add/remove tracks from playlists

• Get playlist details

🎯 Recommendations

• Get personalized recommendations based on:

  • Seed tracks, artists, or genres

  • Mood preferences (energy, danceability, valence)

  • Automatic recommendations from recent listening history

• Get available genre seeds

💬 Intelligent Prompts

• Discover Music: Get recommendations based on mood and preferences

• Analyze Now Playing: Deep analysis of currently playing track

• Create Themed Playlist: Build playlists around themes or activities

Setup

1. Create Spotify App

1. Go to Spotify Developer Dashboard

2. Click "Create app"

3. Fill in:

   • App name: "MCP Spotify" (or any name)

   • App description: "Personal Spotify MCP Server"

   • Redirect URI: http://localhost:3000/callback

4. Check "Web API" under "Which API/SDKs are you planning to use?"

5. Agree to terms and click "Save"

6. Click "Settings" to view your Client ID and Client Secret

2. Configure Environment

Create a .env file in the project root:

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://localhost:3000/callback

3. Build the Server

npm install
npm run build

4. Configure Claude Desktop

Edit your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the MCP server configuration:

{
  "mcpServers": {
    "mcp-spotify": {
      "command": "node",
      "args": [
        "C:\\path\\to\\mcp-spotify\\build\\index.js"
      ]
    }
  }
}

Replace C:\\path\\to\\mcp-spotify with the actual path to this project.

5. First Run Authentication

1. Restart Claude Desktop

2. The server will automatically open a browser for Spotify authentication

3. Log in and authorize the app

4. You'll be redirected to a success page

5. Tokens are saved to ~/.mcp-spotify/tokens.json

Available Tools

Search

• search_tracks - Search for tracks

• search_albums - Search for albums

• search_artists - Search for artists

• search_playlists - Search for playlists

Playback

• get_playback_state - Get current playback information

• playback_control - Control playback (play, pause, skip, previous, shuffle, volume, seek)

Library

• get_saved_tracks - Get user's saved tracks

• save_tracks - Save tracks to library

• remove_saved_tracks - Remove tracks from library

• get_recently_played - Get recently played tracks (useful for recommendations)

Playlists

• get_playlists - Get user's playlists

• create_playlist - Create a new playlist

• add_tracks_to_playlist - Add tracks to a playlist

Recommendations

• get_recommendations - Get track recommendations based on seeds and preferences (supports use_recent_listening parameter)

• get_genre_seeds - Get list of available genre seeds

Available Prompts

discover_music

Discover new music based on your mood, genres, and listening preferences.

Arguments:

• mood (optional): Desired mood (energetic, chill, happy, melancholic)

• genre (optional): Preferred genre

Example: "Discover energetic electronic music"

analyze_now_playing

Get detailed analysis of the currently playing track including audio features and recommendations.

Example: "Analyze what I'm listening to"

create_themed_playlist

Create a playlist based on a theme, mood, or activity.

Arguments:

• theme: Theme or mood (e.g., "Workout", "Study", "Road Trip")

• size (optional): Number of tracks (default: 20)

Example: "Create a chill study playlist with 30 songs"

Example Interactions

You: "What am I currently listening to?"
→ Uses get_playback_state to show current track

You: "Find me some energetic electronic music"
→ Uses search_tracks or get_recommendations with appropriate filters

You: "Create a workout playlist"
→ Uses create_themed_playlist prompt to search, gather tracks, and create playlist

You: "Save this track to my library"
→ Uses save_tracks to add the current or mentioned track

You: "Skip to the next song"
→ Uses playback_control with action: "skip"

Project Structure

src/
  ├── index.ts                 # Main entry point, server setup
  ├── auth.ts                  # OAuth 2.0 authentication flow
  ├── spotify-client.ts        # HTTP client for Spotify API
  ├── logger.ts                # Logging utility
  ├── types.ts                 # TypeScript type definitions
  ├── utils.ts                 # Helper utilities
  ├── tools/
  │   ├── search.ts            # Search functionality
  │   ├── playback.ts          # Playback control
  │   ├── library.ts           # Library management
  │   ├── playlists.ts         # Playlist operations
  │   ├── recommendations.ts   # Recommendations logic
  │   └── declarations/
  │       └── *.ts             # Tool registration
  └── prompts/
      └── declarations/
          └── *.ts             # Prompt registration

Troubleshooting

"Spotify API error: 401"

• Tokens may be expired. Delete ~/.mcp-spotify/tokens.json and restart Claude

• Check that your Client ID and Client Secret are correct in .env

"No playback device found"

• Open Spotify on any device (desktop, mobile, web)

• Start playing any track to activate a device

• The API requires an active device for playback control

Recommendations returning 404

• This is expected! Spotify deprecated the old recommendations API

• The server now uses Search API with filters as a replacement

Technical Details

• Language: TypeScript

• Runtime: Node.js v23.9.0

• MCP SDK: @modelcontextprotocol/sdk v1.20.0

• Transport: stdio

• Auth: OAuth 2.0 Authorization Code Flow with refresh tokens

• Token Storage: ~/.mcp-spotify/tokens.json (auto-refreshed)

License

MIT