Skip to main content
Glama

Spotify Overload - More Tools (18) | More Functions | More Rocking Out

by Beerspitnight
GitHub
Python
MIT License
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Spotify-mcp-Overload

A Model Context Protocol (MCP) server that enables Claude Code CLI or Desktop to interact with Spotify for playlist curation and management, among other goodies.

Rock Out with The Following Features:

  • ๐Ÿง  Smart playlist curation

  • ๐Ÿ›ค๏ธ Deep track identification

  • ๐Ÿ•บ Song analysis (bpm, danceability, etc.)

  • ๐Ÿš€ Discovery & Recommendation (w/ seed validation)

Features

๐ŸšฆCore Playlist Management

  • Create playlists

  • Search for tracks

  • Add tracks to playlists (with automatic rate limit handling)

  • Remove tracks from playlists (with automatic rate limit handling)

  • Get user playlists

  • Get playlist tracks

๐Ÿง  Smart Curation & Discovery

  • Get your top tracks - See what you listen to most (by time period)

  • Get track recommendations (with seed validation)

  • Create curated playlists - Automated playlist based on your top tracks + recommendations

  • Find duplicate tracks in playlists

๐Ÿ“ˆ Audio Analysis

  • Get audio features - BPM, musical key, energy, danceability, valence, acousticness

  • Multi-source data - GetSongBPM API + MusicBrainz/AcousticBrainz waterfall

  • Smart caching - 30-day TTL, positive/negative caching to reduce API calls

  • No preview required - Works with ISRC lookups, not dependent on 30s previews

  • Coverage: ~70-90% for popular/older tracks, ~20-40% for recent releases (2020+)

๐Ÿ› ๏ธ Reliability Features

  • Automatic retry on Spotify API rate limits (HTTP 429)

  • Batch processing for large operations (100+ tracks)

  • Async execution - Audio analysis runs in thread pool (no blocking)

Prerequisites

  • Python 3.10 or higher

  • Spotify account

  • Spotify Developer App (for API credentials)

Setup

1. Get Spotify API Credentials

  1. Go to Spotify Developer Dashboard

  2. Click "Create app"

  3. Fill in:

    • App name: "spotify-mcp-enhanced-music-overload"

    • App description: "MCP server for Claude integration"

    • Redirect URI: http://127.0.0.1:8888/callback

    • APIs used: Check "Web API"

  4. Accept terms and click "Save"

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

2. Install Dependencies

cd spotify-mcp pip install -e .

This installs all required dependencies including audio features support.

3. Get Your Free GetSongBPM API Key (Optional but Recommended)

For enhanced audio features coverage:

  1. Go to GetSongBPM API

  2. Sign up for a free API key

4. Configure Environment

# Copy the example env file cp .env.example .env # Edit .env and add your credentials: # SPOTIFY_CLIENT_ID=your_actual_client_id # SPOTIFY_CLIENT_SECRET=your_actual_client_secret # GETSONGBPM_API_KEY=your_api_key (optional but recommended)

5. First Run Authentication

The first time you run the server, it will:

  1. Open your browser automatically

  2. Ask you to authorize the application

  3. Redirect to http://127.0.0.1:8888/callback

  4. Save the authentication token locally in .spotify_cache

Note: The redirect URL will show an error in your browser (this is normal). The authentication token is extracted from the URL automatically.

After the first run, the token is cached and you won't need to authenticate again unless it expires.

Usage

With Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{ "mcpServers": { "spotify": { "command": "/opt/miniconda3/bin/python", "args": ["/absolute/path/to/spotify-mcp/src/server.py"], "env": { "SPOTIFY_CLIENT_ID": "your_client_id", "SPOTIFY_CLIENT_SECRET": "your_client_secret", "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback", "SPOTIFY_CACHE_PATH": "/absolute/path/to/.spotify_cache" } } } }

Important:

  • Use absolute path to Python (e.g., /opt/miniconda3/bin/python or /usr/bin/python3) - find it with which python

  • Use absolute paths for all file paths, not relative paths

  • Replace /absolute/path/to/spotify-mcp with your actual path

  • Replace your_client_id and your_client_secret with your actual credentials

Restart Claude Desktop after adding the configuration.

Tip: See TESTING_GUIDE.md for comprehensive Claude Desktop setup instructions.

With Claude Code CLI

Recommended for large playlists and complex workflows! Claude Code CLI has a much larger context window than Claude Desktop, making it ideal for:

  • Creating playlists with 100+ tracks

  • Multi-step curation workflows

  • Batch operations across multiple playlists

Add to your settings file:

Location: ~/.claude/settings.json

{ "mcpServers": { "spotify": { "description": "Spotify playlist curation and management. 10 tools for smart playlist creation.", "command": "/opt/miniconda3/bin/python", "args": ["/absolute/path/to/spotify-mcp/src/server.py"], "env": { "SPOTIFY_CLIENT_ID": "your_client_id", "SPOTIFY_CLIENT_SECRET": "your_client_secret", "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback", "SPOTIFY_CACHE_PATH": "/absolute/path/to/.spotify_cache" }, "enabled": true } } }

Important:

  • Use absolute path to Python - find it with which python

  • Use absolute paths for all file paths

  • Restart Claude Code CLI after adding configuration

  • See CLAUDE_CODE_CLI_SETUP.md for detailed setup guide

Example Conversations with Claude

Once configured, you can ask Claude things like:

Create a Playlist

You: Create a workout playlist called "Morning Energy" with an upbeat description Claude: [Uses create_playlist tool] โœ… Created playlist: Morning Energy URL: https://open.spotify.com/playlist/abc123

Search and Add Tracks

You: Find some high-energy electronic music and add the top 5 tracks to my Morning Energy playlist Claude: [Uses search_tracks and add_tracks_to_playlist tools] Found 20 tracks. Adding top 5 to your playlist... โœ… Added 5 tracks to playlist

Get Recommendations

You: Based on my current "Psychedelic" playlist, recommend 10 similar songs Claude: [Uses get_playlist_tracks and get_recommendations tools] Here are 10 recommendations based on your playlist...

List Your Playlists

You: Show me all my playlists Claude: [Uses get_user_playlists tool] Found 15 playlists: 1. Psychedelic (Public) - 25 tracks 2. Dub Reggae (Private) - 40 tracks ...

Remove Tracks

You: Remove all tracks by "Black Sabbath" from my workout playlist Claude: [Uses get_playlist_tracks and remove_tracks_from_playlist tools] Found 3 tracks by Black Sabbath. Removing... โœ… Removed 3 tracks from playlist

Find Duplicates

You: Find duplicate songs in my "Favorites" playlist Claude: [Uses find_duplicates tool] Found 5 duplicate tracks: 1. "I Was On A Mountain" by Hot Water Music - 2 occurrences 2. "Suffer" by Bad Religion - 2 occurrences ...

Get Your Top Tracks

You: Show me my top 20 most-played tracks from the last 6 months Claude: [Uses get_top_tracks tool] Your top 20 tracks (last 6 months): 1. Saboteurs by Dave Hause 2. Web in Front by Archers Of Loaf 3. Cabin Fever by Slomosa ...

Create Curated Playlist

You: Create a personalized playlist based on my top tracks from the last month, including similar recommendations Claude: [Uses create_curated_playlist_from_top_tracks tool] โœ… Created curated playlist: Personalized Mix ๐Ÿ“Š Summary: - Total tracks added: 50 - Your top tracks: 20 - Recommendations: 30 ๐Ÿ”— Playlist URL: https://open.spotify.com/playlist/abc123

Get Audio Features ๐ŸŽต

You: Analyze the audio features for Hot Water Music's "I Was On A Mountain" Claude: [Uses search_tracks and get_audio_features tools] ๐ŸŽต Audio Features (The Mighty Mighty Bosstones - I Hope I Never Lose My Wallet) ๐ŸŽผ Musical Properties: - Tempo: 102.0 BPM - Key: A minor - Time Signature: 4/4 ๐Ÿ“Š Energy & Mood: - Danceability: 0.440 (moderate) - Acousticness: 0.010 (very electric) โ„น๏ธ Data Source: GetSongBPM API

Use Cases:

  • Find tracks with similar BPM for DJ mixes and workout playlists

  • Detect musical key for harmonic mixing (DJs)

  • Filter tracks by energy/danceability for themed playlists

  • Analyze mood (valence) and acousticness for curation

  • Build setlists with consistent tempo/energy flow

Available Tools

Tool

Description

Features

create_playlist

Create a new Spotify playlist

-

search_tracks

Search for tracks by name, artist, album, etc.

-

add_tracks_to_playlist

Add tracks to an existing playlist

Auto-batching (100 tracks/batch), Rate limit retry

remove_tracks_from_playlist

Remove tracks from a playlist

Auto-batching (100 tracks/batch), Rate limit retry

get_user_playlists

List all user playlists

-

get_playlist_tracks

Get all tracks from a playlist

Pagination handling

get_recommendations

Get track recommendations based on seeds

Seed validation (requires at least one seed)

find_duplicates

Find duplicate tracks in a playlist

Case-insensitive matching

get_top_tracks

Get user's most-played tracks

Time periods: 4 weeks, 6 months, all time

create_curated_playlist_from_top_tracks

Auto-create playlist from top tracks + recommendations

One-command automation

get_audio_features

๐ŸŽต

Analyze track audio (BPM, key, energy, etc.)

Multi-source (GetSongBPM, MusicBrainz, AcousticBrainz), 30-day cache, ~70-90% coverage

get_playlist_stats

Get comprehensive playlist statistics

Duration, genre breakdown, avg release year

merge_playlists

Merge multiple playlists with deduplication

Auto-dedup, custom descriptions

compare_playlists

Find shared and unique tracks

Venn diagram analysis

set_collaborative

Toggle playlist collaborative status

Enable/disable collaboration

get_artist_discography

Get artist's complete discography

Albums, singles, compilations

get_related_artists

Find similar artists

Spotify similarity algorithm

get_artist_top_tracks

Get artist's most popular tracks

Country-specific results

Total: 18 tools available

Reliability Features

Automatic Rate Limit Handling

The server automatically handles Spotify API rate limits (HTTP 429):

  • Reads the Retry-After header from Spotify

  • Waits the specified time

  • Retries the operation once

  • Logs rate limit events to stderr

This makes bulk operations (adding/removing 100+ tracks) reliable and resilient.

Batch Processing

Operations that modify playlists automatically batch requests:

  • Max 100 tracks per API call (Spotify's limit)

  • Handles playlists of any size

  • Maintains operation atomicity within batches

Input Validation

  • get_recommendations validates that at least one seed is provided before making API calls

  • Prevents unnecessary API requests with clear error messages

Troubleshooting

"Authentication failed" error

  • Verify your Client ID and Client Secret are correct

  • Make sure the Redirect URI in your Spotify app settings matches exactly: http://127.0.0.1:8888/callback

  • Delete .spotify_cache and try authenticating again

"No module named 'mcp'" error

  • Run pip install -e . from the project directory

  • Make sure you're using Python 3.10+

"spawn python ENOENT" error in Claude Desktop

  • Use the full path to your Python interpreter in the config

  • Find it with: which python or which python3

  • Example: "command": "/opt/miniconda3/bin/python" instead of "command": "python"

Claude Desktop doesn't show Spotify tools

  • Verify the JSON configuration syntax is correct

  • Check that all paths are absolute (not relative)

  • Use full Python path (see "spawn python ENOENT" above)

  • Restart Claude Desktop after configuration changes

  • Check Claude Desktop logs for errors

Browser doesn't open for authentication

  • The first run requires a browser. Run the server manually once:

    cd spotify-mcp/src python server.py

  • After authentication succeeds, the token is cached for Claude Desktop/CLI

"No audio features available" message

  • Track may be too recent (post-2020 has ~20-40% coverage)

  • Older/classic tracks have better coverage (~70-90%)

  • GetSongBPM API key improves coverage significantly

  • MusicBrainz/AcousticBrainz stopped collecting data in 2022

  • Features are cached for 30 days after lookup

Security Notes

  • Never commit your .env file or .spotify_cache file to version control

  • The .spotify_cache file contains your access and refresh tokens

  • Client Secret should be kept private

  • This server is designed for personal use on your local machine

Development

Running Tests

pip install -e ".[dev]" pytest

Project Structure

spotify-mcp/ โ”œโ”€โ”€ src/ โ”‚ โ”œโ”€โ”€ features/ # Audio features module (Phase 2) โ”‚ โ”‚ โ”œโ”€โ”€ __init__.py โ”‚ โ”‚ โ”œโ”€โ”€ models.py # Pydantic data models โ”‚ โ”‚ โ”œโ”€โ”€ cache.py # File-based caching (30-day TTL) โ”‚ โ”‚ โ”œโ”€โ”€ service.py # Multi-source orchestration โ”‚ โ”‚ โ””โ”€โ”€ clients/ # API clients โ”‚ โ”‚ โ”œโ”€โ”€ getsongbpm.py # GetSongBPM API client โ”‚ โ”‚ โ”œโ”€โ”€ musicbrainz.py # MusicBrainz ISRC lookup โ”‚ โ”‚ โ””โ”€โ”€ acousticbrainz.py # AcousticBrainz features โ”‚ โ”œโ”€โ”€ clients/ โ”‚ โ”‚ โ””โ”€โ”€ spotify_client.py # Spotify API wrapper โ”‚ โ”œโ”€โ”€ logic/ โ”‚ โ”‚ โ”œโ”€โ”€ playlist_logic.py # Playlist intelligence โ”‚ โ”‚ โ””โ”€โ”€ artist_logic.py # Artist deep dive โ”‚ โ””โ”€โ”€ server.py # Main MCP server โ”œโ”€โ”€ pyproject.toml # Dependencies โ”œโ”€โ”€ .env.example # Example environment variables โ””โ”€โ”€ README.md

Credits

Access from https://getsongbpm.com/ via their free API provides song-analysis including beats-per-minute. Thanks, GetSongBPM.com

License

MIT License - feel free to modify and distribute. Make it better. Make it cooler.

Contributing

Issues and pull requests welcome! This implementation includes core features and can be extended with:

  • More Spotify API endpoints

  • Advanced playlist curation algorithms

  • User library management

  • Collaborative filtering

  • Setlist generators (DJ sets, concert setlists)

  • Additional audio analysis sources

Credits

This project is built on top of excellent open-source tools and APIs:

Core Dependencies

Audio Features Data Sources

  • GetSongBPM API - Primary source for tempo, key, and audio features - mucho gracias

  • MusicBrainz - Open music encyclopedia for ISRC lookups - killer

  • AcousticBrainz - Crowd-sourced acoustic analysis database (archived 2022) - very cool

Development Tools

Special Thanks

My mom and Dad. Claude in all his different clothes

Resources

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

MCP server for Spotify playlist curation and management. 18 tools for song analysis, smart playlist creation, top tracks analysis, and automated recommendations.

  1. Rock Out with The Following Features:
    1. Features
      1. ๐ŸšฆCore Playlist Management
      2. ๐Ÿง  Smart Curation & Discovery
      3. ๐Ÿ“ˆ Audio Analysis
      4. ๐Ÿ› ๏ธ Reliability Features
    2. Prerequisites
      1. Setup
        1. 1. Get Spotify API Credentials
        2. 2. Install Dependencies
        3. 3. Get Your Free GetSongBPM API Key (Optional but Recommended)
        4. 4. Configure Environment
        5. 5. First Run Authentication
      2. Usage
        1. With Claude Desktop
        2. With Claude Code CLI
      3. Example Conversations with Claude
        1. Create a Playlist
        2. Search and Add Tracks
        3. Get Recommendations
        4. List Your Playlists
        5. Remove Tracks
        6. Find Duplicates
        7. Get Your Top Tracks
        8. Create Curated Playlist
        9. Get Audio Features ๐ŸŽต
      4. Available Tools
        1. Reliability Features
          1. Automatic Rate Limit Handling
          2. Batch Processing
          3. Input Validation
        2. Troubleshooting
          1. "Authentication failed" error
          2. "No module named 'mcp'" error
          3. "spawn python ENOENT" error in Claude Desktop
          4. Claude Desktop doesn't show Spotify tools
          5. Browser doesn't open for authentication
          6. "No audio features available" message
        3. Security Notes
          1. Development
            1. Running Tests
            2. Project Structure
          2. Credits
            1. License
              1. Contributing
                1. Credits
                  1. Core Dependencies
                  2. Audio Features Data Sources
                  3. Development Tools
                  4. Special Thanks
                2. Resources

                  Related MCP Servers

                  • Spotify MCP

                    ashwanth1109
                    A
                    security
                    -
                    license
                    A
                    quality
                    A FastMCP tool that enables control of Spotify through natural language commands in Cursor Composer, allowing users to manage playback, search for content, and interact with playlists.
                    Last updated -
                    5

                  • Spotify Playlist MCP Server

                    kylestratis
                    A
                    security
                    A
                    license
                    A
                    quality
                    Enables creating and managing Spotify playlists using natural language with advanced similarity matching across 8 different algorithms. Supports finding similar tracks based on audio features, mood, energy, genre, and custom weighted parameters to build personalized playlists automatically.
                    Last updated -
                    9
                    1
                    MIT License

                  View all related MCP servers

                  New MCP Servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/Beerspitnight/Bruno'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server