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:

git clone <repository-url>
cd spotify-playlist-mcp

2. Install dependencies:

uv sync

3. Configure environment variables:

cp .env.example .env
# Edit .env and add your SPOTIFY_ACCESS_TOKEN

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)

uv run mcp dev server.py

Direct Execution

uv run python server.py

Install for Claude Desktop

uv run mcp install server.py

Example Use Cases

Find Similar Tracks in a Playlist

"Find songs similar to track [ID] within my workout playlist"

Create a Playlist Based on a Track

"Find tracks similar to [track name] using the energy_match strategy
and create a playlist called 'High Energy Workout'"

Custom Weighted Similarity

"Find tracks similar to this song, but prioritize energy and danceability
more than other features (weights: energy=5.0, danceability=5.0)"

Mood-Based Playlist from Artist

"Create a calm acoustic playlist based on [artist name]'s style
using the mood_match strategy"

Search Saved Tracks

"Find all tracks in my saved library that sound similar to this song"

Genre-Based Playlist Filtering

"Create a playlist with tracks from my Discover Weekly that have
the same genre as this track I'm listening to"

Similarity Engine Examples

Example 1: Find Similar Tracks in a Playlist

{
  "track_id": "3n3Ppam7vgaVa1iaRUc9Lp",
  "strategy": "euclidean",
  "scope": "playlist",
  "scope_id": "37i9dQZF1DXcBWIGoYBM5M",
  "limit": 10,
  "action": "return_tracks"
}

Example 2: Create High-Energy Workout Playlist

{
  "track_id": "4iV5W9uYEdYUVa79Axb7Rh",
  "strategy": "energy_match",
  "scope": "catalog",
  "limit": 30,
  "action": "create_playlist",
  "playlist_name": "High Energy Workout"
}

Example 3: Custom Weighted Similarity

{
  "track_id": "7qiZfU4dY1lWllzX7mPBI",
  "strategy": "weighted",
  "weights": {
    "energy": 5.0,
    "danceability": 5.0,
    "valence": 3.0,
    "acousticness": 0.5,
    "tempo": 2.0
  },
  "scope": "catalog",
  "limit": 20,
  "action": "create_playlist",
  "playlist_name": "Custom Mix"
}

Example 4: Find Similar Tracks by Artist Style

{
  "artist_id": "0OdUWJ0sBjDrqHygGUXeCF",
  "strategy": "cosine",
  "scope": "saved_tracks",
  "limit": 15,
  "action": "add_to_playlist",
  "target_playlist_id": "5FqPqTauQoRPRxJBQC8C2N"
}

Example 5: Genre-Based Playlist Filtering

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

{
  "track_id": "3n3Ppam7vgaVa1iaRUc9Lp",
  "strategy": "genre_match",
  "scope": "playlist",
  "scope_id": "37i9dQZF1DXcBWIGoYBM5M",
  "limit": 20,
  "action": "create_playlist",
  "playlist_name": "Same Genre from Discover Weekly"
}

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.