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:

To build playlists using natural language and with one of several similarity metrics. The ideal would be ephemeral playlists, but alas.
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

spotify_search_tracks - Search for tracks by name, artist, or query
spotify_get_track - Get detailed information about a specific track
spotify_get_recommendations - Get track recommendations with tunable parameters
spotify_create_playlist - Create a new Spotify playlist
spotify_add_tracks_to_playlist - Add tracks to an existing playlist
spotify_get_user_playlists - List user's playlists with pagination
spotify_get_playlist_tracks - Get tracks from a specific playlist

Advanced Similarity Tools

spotify_get_audio_features - Get detailed audio features for tracks
spotify_find_similar_tracks - Advanced similarity engine (see below)

Similarity Engine

How It Works

The similarity engine finds similar tracks using two approaches:

Audio Feature Analysis: Analyzes sonic characteristics like energy, tempo, and danceability
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:

euclidean (Default) - Overall similarity across all features using Euclidean distance
weighted - Custom weighted similarity - specify importance of each feature
cosine - Angular similarity (good for high-dimensional matching)
manhattan - City-block distance metric
energy_match - Focus on energy and danceability for workout/party playlists
mood_match - Focus on valence and acousticness for mood-based matching
rhythm_match - Focus on tempo for rhythm-based similarity
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

Python 3.12+ (managed with mise)
uv for dependency management
Spotify Developer Account and API credentials

Setup

Clone the repository:

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

Install dependencies:

uv sync

Configure environment variables:

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

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:

Feature Normalization - Normalizes audio features to 0-1 range
Similarity Calculators - Pluggable distance/similarity functions
Scope Handlers - Extract candidate tracks from different sources
Action Executors - Handle different output actions

Adding Custom Strategies

To add a new similarity strategy:

Add the strategy to the SimilarityStrategy enum
Implement the calculation logic in _calculate_similarity()
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

Token Management: Implement token refresh logic for production use
Scope Selection: Use specific scopes (playlist/artist/album) for better performance
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
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)
Batch Operations: When analyzing multiple tracks, use batch endpoints
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.