nicklaustrup/mcp-spotify

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