Spotify Playlist MCP Server

A Model Context Protocol server for creating playlists on the fly with natural language, including using one of several similarity methods for similar tracks.

This was built to scratch two personal itches:

1. To build playlists using natural language and with one of several similarity metrics. The ideal would be ephemeral playlists, but alas.

2. To play with the new Claude skills and see how much it aids in AI-assisted coding. Verdict: It may chew up tokens but works very well.

** WARNING **: This still needs to put through its paces in real-world testing and have some evaluations written for it.

Features

Core Playlist Management

• Create and manage Spotify playlists

• Search tracks across Spotify's catalog

• Get track details and recommendations

• Browse user playlists and playlist contents

Advanced Similarity Engine

• Audio Feature Analysis: Extract and analyze acousticness, danceability, energy, tempo, valence, and more

• Multiple Similarity Algorithms: Choose from 8 different strategies (Euclidean, Cosine, Weighted, Manhattan, Energy Match, Mood Match, Rhythm Match, Genre Match)

• Genre-Based Matching: Find tracks with similar artist genres within playlists or collections

• Customizable Feature Weights: Fine-tune similarity calculations by weighting specific audio features

• Flexible Search Scopes: Search entire catalog, within playlists, artist discographies, albums, or saved tracks

• Automated Actions: Find similar tracks and automatically create playlists or add to existing ones

Available Tools

Basic Tools

1. spotify_search_tracks - Search for tracks by name, artist, or query

2. spotify_get_track - Get detailed information about a specific track

3. spotify_get_recommendations - Get track recommendations with tunable parameters

4. spotify_create_playlist - Create a new Spotify playlist

5. spotify_add_tracks_to_playlist - Add tracks to an existing playlist

6. spotify_get_user_playlists - List user's playlists with pagination

7. spotify_get_playlist_tracks - Get tracks from a specific playlist

Advanced Similarity Tools

8. spotify_get_audio_features - Get detailed audio features for tracks

9. spotify_find_similar_tracks - Advanced similarity engine (see below)

Similarity Engine

How It Works

The similarity engine finds similar tracks using two approaches:

1. Audio Feature Analysis: Analyzes sonic characteristics like energy, tempo, and danceability

2. Genre Matching: Compares artist genres for style-based similarity

For audio feature analysis, the engine uses Spotify's audio analysis API to extract features like:

• Acousticness (0-1): Confidence that track uses acoustic instruments

• Danceability (0-1): How suitable for dancing

• Energy (0-1): Intensity and activity level

• Instrumentalness (0-1): Likelihood of no vocals

• Valence (0-1): Musical positiveness (happiness/cheerfulness)

• Tempo (BPM): Speed of the track

• Loudness (dB): Overall volume

• Speechiness (0-1): Presence of spoken words

• Liveness (0-1): Audience presence (live performance)

Similarity Strategies

Choose from 8 different algorithms:

1. euclidean (Default) - Overall similarity across all features using Euclidean distance

2. weighted - Custom weighted similarity - specify importance of each feature

3. cosine - Angular similarity (good for high-dimensional matching)

4. manhattan - City-block distance metric

5. energy_match - Focus on energy and danceability for workout/party playlists

6. mood_match - Focus on valence and acousticness for mood-based matching

7. rhythm_match - Focus on tempo for rhythm-based similarity

8. genre_match - Match tracks based on artist genres (exact and partial matches)

Search Scopes

Control where to search for similar tracks:

• catalog - Search entire Spotify catalog (uses recommendations API)

• playlist - Find similar tracks within a specific playlist

• artist - Search within an artist's discography

• album - Find similar tracks within a specific album

• saved_tracks - Search within user's saved library

Actions

Choose what to do with similar tracks:

• return_tracks - Just return the list with similarity scores

• create_playlist - Automatically create a new playlist with similar tracks

• add_to_playlist - Add similar tracks to an existing playlist

Installation

Prerequisites

1. Python 3.12+ (managed with mise)

2. uv for dependency management

3. Spotify Developer Account and API credentials

Setup

1. Clone the repository:

2. Install dependencies:

3. Configure environment variables:

4. Get your Spotify access token (see .env.example for detailed instructions):

   • Go to Spotify Developer Dashboard

   • Create an app

   • Get your Client ID and Client Secret

   • Generate an access token with required scopes:

     • playlist-modify-public

     • playlist-modify-private

     • playlist-read-private

     • user-read-private

Usage

Running the Server

Development Mode (with MCP Inspector)

Direct Execution

Install for Claude Desktop

Example Use Cases

Find Similar Tracks in a Playlist

Create a Playlist Based on a Track

Custom Weighted Similarity

Mood-Based Playlist from Artist

Search Saved Tracks

Genre-Based Playlist Filtering

Similarity Engine Examples

Example 1: Find Similar Tracks in a Playlist

Example 2: Create High-Energy Workout Playlist

Example 3: Custom Weighted Similarity

Example 4: Find Similar Tracks by Artist Style

Example 5: Genre-Based Playlist Filtering

Find tracks from a playlist that match the genre of a specific track:

Note: genre_match strategy requires a specific scope (playlist, artist, album, or saved_tracks) and does not work with the catalog scope.

Architecture

Modular Design

The similarity engine is built with modularity in mind:

1. Feature Normalization - Normalizes audio features to 0-1 range

2. Similarity Calculators - Pluggable distance/similarity functions

3. Scope Handlers - Extract candidate tracks from different sources

4. Action Executors - Handle different output actions

Adding Custom Strategies

To add a new similarity strategy:

1. Add the strategy to the SimilarityStrategy enum

2. Implement the calculation logic in _calculate_similarity()

3. Document the strategy in tool descriptions

API Reference

spotify_find_similar_tracks

Parameters:

• track_id (Optional[str]): Source track ID

• artist_id (Optional[str]): Source artist ID

• playlist_id (Optional[str]): Source playlist ID

• strategy (SimilarityStrategy): Algorithm to use

• weights (Optional[FeatureWeights]): Custom feature weights

• scope (SearchScope): Where to search

• scope_id (Optional[str]): ID for scope (playlist/artist/album)

• limit (int): Number of results (1-100)

• min_similarity (Optional[float]): Minimum similarity threshold

• action (SimilarityAction): What to do with results

• playlist_name (Optional[str]): Name for new playlist

• target_playlist_id (Optional[str]): Target for adding tracks

• response_format (ResponseFormat): 'markdown' or 'json'

Returns:

• List of similar tracks with similarity scores

• OR playlist creation confirmation

• OR add to playlist confirmation

Troubleshooting

Audio Features Deprecated Error

If you encounter errors about audio features being deprecated:

• Ensure you have extended mode access on your Spotify app

• Note: Audio features endpoint was deprecated for NEW applications in November 2024

• Existing applications with extended mode access can still use it

Authentication Errors

• Access tokens expire after 1 hour - refresh regularly

• Ensure all required scopes are granted

• Check that your token is correctly set in .env

Rate Limiting

• Spotify API has rate limits - the server handles 429 errors gracefully

• If searching large playlists, be patient as it may take time

Best Practices

1. Token Management: Implement token refresh logic for production use

2. Scope Selection: Use specific scopes (playlist/artist/album) for better performance

3. Strategy Choice:

   • Use euclidean for general similarity

   • Use energy_match for workout/party playlists

   • Use mood_match for relaxation/study playlists

   • Use rhythm_match for tempo-based matching (running, dancing)

   • Use genre_match to filter playlists by genre similarity

   • Use weighted when you know which features matter most

4. Genre Match Considerations:

   • Requires specific scope (playlist, artist, album, or saved_tracks)

   • Does not work with catalog scope

   • Best for filtering existing collections by genre

   • Uses artist genres (tracks without artist genre data will be skipped)

5. Batch Operations: When analyzing multiple tracks, use batch endpoints

6. Error Handling: Always check response for errors before proceeding

Contributing

Contributions are welcome! Areas for improvement:

• Additional similarity strategies

• More sophisticated feature weighting algorithms

• Tempo range matching with BPM bands

• Key and mode compatibility checking

• Audio analysis integration (bars, beats, segments)

• Advanced genre hierarchies and taxonomy

• Multi-artist collaboration detection

Acknowledgments

• Built with FastMCP as it appears in the MCP Python SDK

• Uses Spotify Web API

• Follows Model Context Protocol specification

• Uses the mcp-builder Claude skill to improve code generation.

Support

For issues, questions, or feature requests, please open an issue on GitHub.