Spotify MCP

🚀 Spotify Playlist MCP Server

A Model Context Protocol server that enables on-the-fly playlist creation using natural language, incorporating multiple similarity methods for finding similar tracks.

This project was developed to address two personal needs:

1. To create playlists using natural language and multiple similarity metrics. The ideal goal is to generate ephemeral playlists, though it's not fully realized yet.
2. To experiment with the new Claude skills and assess their effectiveness in AI-assisted coding. Conclusion: It may consume a large number of tokens, but it performs very well.

⚠️ Important Note

This project still needs to undergo real-world testing and have some evaluations written for it.

✨ Features

Core Playlist Management

• Create and manage Spotify playlists.
• Search for tracks across Spotify's entire catalog.
• Retrieve detailed track information and recommendations.
• Browse user playlists and view playlist contents.

Advanced Similarity Engine

• Audio Feature Analysis: Extract and analyze various acoustic features, including acousticness, danceability, energy, tempo, valence, and more.
• Multiple Similarity Algorithms: Choose from 8 different strategies, such as Euclidean, Cosine, Weighted, Manhattan, Energy Match, Mood Match, Rhythm Match, and Genre Match.
• Genre-Based Matching: Find tracks with similar artist genres within playlists or collections.
• Customizable Feature Weights: Fine-tune similarity calculations by assigning weights to specific audio features.
• Flexible Search Scopes: Search within the entire catalog, specific playlists, artist discographies, albums, or user-saved tracks.
• Automated Actions: Automatically find similar tracks and create new playlists or add them 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 adjustable 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 playlists with pagination support.
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: Utilize the advanced similarity engine (see details below).

💻 Similarity Engine

How It Works

The similarity engine employs two approaches to find similar tracks:

1. Audio Feature Analysis: Analyze sonic characteristics such as energy, tempo, and danceability.
2. Genre Matching: Compare artist genres to identify style-based similarities.

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

• Acousticness (0 - 1): Indicates the confidence that a track uses acoustic instruments.
• Danceability (0 - 1): Measures how suitable a track is for dancing.
• Energy (0 - 1): Represents the intensity and activity level of a track.
• Instrumentalness (0 - 1): Estimates the likelihood of a track having no vocals.
• Valence (0 - 1): Reflects the musical positiveness (happiness/cheerfulness) of a track.
• Tempo (BPM): The speed of the track.
• Loudness (dB): The overall volume of the track.
• Speechiness (0 - 1): Indicates the presence of spoken words in a track.
• Liveness (0 - 1): Suggests the presence of an audience (live performance).

Similarity Strategies

Choose from 8 different algorithms:

1. euclidean (Default): Calculates overall similarity across all features using the Euclidean distance.
2. weighted: Allows for custom weighted similarity by specifying the importance of each feature.
3. cosine: Measures angular similarity, which is suitable for high-dimensional matching.
4. manhattan: Uses the city-block distance metric.
5. energy_match: Focuses on energy and danceability, ideal for workout/party playlists.
6. mood_match: Emphasizes valence and acousticness for mood-based matching.
7. rhythm_match: Concentrates on tempo for rhythm-based similarity.
8. genre_match: Matches tracks based on artist genres (both exact and partial matches).

Search Scopes

Control where to search for similar tracks:

• catalog: Search the entire Spotify catalog using the 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 the user's saved library.

Actions

Choose what to do with the similar tracks:

• return_tracks: Simply return the list of tracks with similarity scores.
• create_playlist: Automatically create a new playlist with the similar tracks.
• add_to_playlist: Add the 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. Obtain your Spotify access token (see .env.example for detailed instructions):
   • Navigate to the Spotify Developer Dashboard.
   • Create a new app.
   • Retrieve your Client ID and Client Secret.
   • Generate an access token with the 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: The 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 designed with modularity in mind:

1. Feature Normalization: Normalizes audio features to the 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 the 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 the scope (playlist/artist/album).
• limit (int): Number of results (1 - 100).
• min_similarity (Optional[float]): Minimum similarity threshold.
• action (SimilarityAction): What to do with the results.
• playlist_name (Optional[str]): Name for the new playlist.
• target_playlist_id (Optional[str]): Target playlist ID for adding tracks.
• response_format (ResponseFormat): 'markdown' or 'json'.

Returns:

• A list of similar tracks with similarity scores.
• Or a playlist creation confirmation.
• Or a confirmation of tracks added to a playlist.

🛠️ Troubleshooting

Audio Features Deprecated Error

If you encounter errors regarding deprecated audio features:

• Ensure that your Spotify app has extended mode access.
• Note: The 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 them regularly.
• Ensure that all required scopes are granted.
• Check that your token is correctly set in the .env file.

Rate Limiting

• The Spotify API has rate limits, and the server handles 429 errors gracefully.
• When searching large playlists, be patient as it may take some 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 are most important.
4. Genre Match Considerations:
   • Requires a specific scope (playlist, artist, album, or saved_tracks).
   • Does not work with the 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 the response for errors before proceeding.

👥 Contributing

Contributions are welcome! Areas for improvement include:

• 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.
• Utilizes the Spotify Web API.
• Follows the Model Context Protocol specification.
• Employs the mcp-builder Claude skill to enhance code generation.

🆘 Support

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