Provides comprehensive Spotify integration for playlist management, track search, recommendations, and advanced similarity analysis. Features include creating playlists with natural language, finding similar tracks using multiple algorithms (audio features, genre matching), and managing user's Spotify library with sophisticated filtering and recommendation capabilities.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Spotify Playlist MCP Server create a workout playlist with high-energy tracks similar to 'Eye of the Tiger'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Create and manage Spotify playlists
Search tracks across Spotify's catalog
Get track details and recommendations
Browse user playlists and playlist contents
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
Related MCP server: Spotify MCP Server
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
spotify_get_audio_features - Get detailed audio features for tracks
spotify_find_similar_tracks - Advanced similarity engine (see below)
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)
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)
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
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
Python 3.12+ (managed with mise)
uv for dependency management
Spotify Developer Account and API credentials
Clone the repository:
git clone <repository-url>
cd spotify-playlist-mcpInstall dependencies:
uv syncConfigure environment variables:
cp .env.example .env
# Edit .env and add your SPOTIFY_ACCESS_TOKENGet your Spotify access token (see .env.example for detailed instructions):
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
uv run mcp dev server.pyuv run python server.pyuv run mcp install server.py"Find songs similar to track [ID] within my workout playlist""Find tracks similar to [track name] using the energy_match strategy
and create a playlist called 'High Energy Workout'""Find tracks similar to this song, but prioritize energy and danceability
more than other features (weights: energy=5.0, danceability=5.0)""Create a calm acoustic playlist based on [artist name]'s style
using the mood_match strategy""Find all tracks in my saved library that sound similar to this song""Create a playlist with tracks from my Discover Weekly that have
the same genre as this track I'm listening to"{
"track_id": "3n3Ppam7vgaVa1iaRUc9Lp",
"strategy": "euclidean",
"scope": "playlist",
"scope_id": "37i9dQZF1DXcBWIGoYBM5M",
"limit": 10,
"action": "return_tracks"
}{
"track_id": "4iV5W9uYEdYUVa79Axb7Rh",
"strategy": "energy_match",
"scope": "catalog",
"limit": 30,
"action": "create_playlist",
"playlist_name": "High Energy Workout"
}{
"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"
}{
"artist_id": "0OdUWJ0sBjDrqHygGUXeCF",
"strategy": "cosine",
"scope": "saved_tracks",
"limit": 15,
"action": "add_to_playlist",
"target_playlist_id": "5FqPqTauQoRPRxJBQC8C2N"
}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.
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
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
spotify_find_similar_tracksParameters:
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
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
Access tokens expire after 1 hour - refresh regularly
Ensure all required scopes are granted
Check that your token is correctly set in .env
Spotify API has rate limits - the server handles 429 errors gracefully
If searching large playlists, be patient as it may take time
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
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
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.
For issues, questions, or feature requests, please open an issue on GitHub.
Add tracks to an existing Spotify playlist.
Adds 1-100 tracks to a playlist. Tracks can be inserted at a specific position or
appended to the end. Playlist must be owned by user or be collaborative.
Args:
- playlist_id: Spotify playlist ID (not URI)
- track_uris: List of track URIs, 1-100 (format: "spotify:track:ID", not just IDs)
- position: Optional 0-indexed position to insert (default: append to end)
Returns:
JSON: {"success": true, "snapshot_id": "...", "tracks_added": N, "message": "..."}
Examples:
- "Add this track to my playlist" -> track_uris=["spotify:track:ID"], playlist_id="..."
- "Add 10 songs to workout mix" -> track_uris=[list of URIs]
- "Insert at the beginning" -> position=0
Errors: Returns error for invalid playlist (404), no permission (403), auth failure (401), rate limits (429).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it specifies ownership/collaborative requirements, insertion vs. append behavior, and error conditions (404, 403, 401, 429). While annotations cover basic safety (readOnlyHint=false, destructiveHint=false), the description provides practical implementation details that help the agent understand real-world constraints. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and efficiently organized: purpose statement first, then key constraints, followed by parameter details, return format, examples, and error conditions. Every section adds value with zero redundant information. The examples are practical and illustrate common use cases without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with annotations but 0% schema coverage and an output schema, this description is exceptionally complete. It covers purpose, constraints, all parameters, return values, examples, and error handling. The output schema exists, so the description appropriately focuses on explaining the JSON structure rather than just stating return types. All critical information for correct tool invocation is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage (schema has no parameter descriptions), the description carries the full burden and excels: it clearly explains playlist_id format ('Spotify playlist ID (not URI)'), track_uris format and constraints ('List of track URIs, 1-100 (format: "spotify:track:ID", not just IDs)'), and position behavior ('Optional 0-indexed position to insert (default: append to end)'). Each parameter's purpose and format is thoroughly documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Add tracks to an existing Spotify playlist'), identifies the resource ('Spotify playlist'), and distinguishes from siblings like spotify_create_playlist (which creates new playlists) and spotify_get_playlist_tracks (which reads rather than modifies). The verb+resource combination is precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool ('Playlist must be owned by user or be collaborative') and mentions track quantity limits (1-100). However, it doesn't explicitly contrast with alternatives like spotify_create_playlist for when you need a new playlist instead of adding to an existing one, or when to use this versus other modification tools if they existed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new empty Spotify playlist for the authenticated user.
Creates an empty playlist in the user's library. Use spotify_add_tracks_to_playlist
to add tracks after creation.
Args:
- name: Playlist name, 1-100 characters
- description: Optional description, max 300 characters
- public: Whether playlist is public (default: True)
- collaborative: Whether others can modify (default: False, cannot be True if public is True)
Returns:
JSON: {"success": true, "playlist_id": "...", "name": "...", "url": "...", "message": "..."}
Examples:
- "Create a new workout playlist" -> name="Workout Mix"
- "Make a private playlist" -> name="My Mix", public=False
- "Create collaborative playlist" -> collaborative=True, public=False
Errors: Returns error for collaborative+public, auth failure (401), missing scopes (403), rate limits (429).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds valuable behavioral context beyond this: it mentions auth failure (401), missing scopes (403), and rate limits (429) as potential errors, and clarifies the collaborative/public constraint. It doesn't contradict annotations, but could elaborate more on idempotency or open-world aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by usage guidance, parameter details, return format, examples, and errors. Every section adds value without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with auth and constraints), the description is complete: it covers purpose, usage, parameters, returns, examples, and errors. With an output schema present, it doesn't need to explain return values in depth, and annotations provide safety context, making this thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by detailing all parameters (name, description, public, collaborative) with constraints like character limits, defaults, and the collaborative/public rule. It adds meaning beyond the bare schema, though it doesn't explain the nested 'params' structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Create a new empty Spotify playlist') and resource ('for the authenticated user'), distinguishing it from siblings like spotify_add_tracks_to_playlist and spotify_get_user_playlists. It precisely defines what the tool does without being vague or tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when-to-use guidance by stating 'Use spotify_add_tracks_to_playlist to add tracks after creation,' naming a specific alternative tool. It also clarifies that the playlist is created empty, setting clear expectations for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find tracks similar to a track, artist, or playlist using audio analysis or genre matching.
Centerpiece of the similarity engine. Supports 8 strategies, custom weighting, and automated
playlist creation. For curated playlists, music discovery, and mood-based mixes.
Args:
Source (one required): track_id, artist_id, or playlist_id
Strategy (default: euclidean): euclidean, weighted (needs weights), cosine, manhattan,
energy_match (workout), mood_match (relaxation), rhythm_match (running), genre_match (non-catalog scope only)
Scope (default: catalog): catalog (recommendations API), playlist (needs scope_id),
artist (needs scope_id), album (needs scope_id), saved_tracks
Action (default: return_tracks): return_tracks, create_playlist (needs playlist_name),
add_to_playlist (needs target_playlist_id)
- limit: Results to return, 1-100 (default: 20)
- min_similarity: Optional threshold, 0.0-1.0
- weights: Optional custom weights for 'weighted' strategy (e.g., {"energy": 5.0, "danceability": 5.0})
- response_format: 'markdown' or 'json'
Returns:
return_tracks: List with similarity scores (Markdown or JSON: {"strategy": "...", "scope": "...", "count": N, "tracks": [{track, similarity}]})
create_playlist: {"success": true, "action": "create_playlist", "playlist_id": "...", "playlist_name": "...", "playlist_url": "...", "tracks_added": N, "message": "..."}
add_to_playlist: {"success": true, "action": "add_to_playlist", "playlist_id": "...", "tracks_added": N, "message": "..."}
Examples:
- "Find songs similar to this track" -> track_id, catalog scope
- "Create workout playlist like this" -> track_id, energy_match, create_playlist
- "Filter playlist by genre" -> track_id, genre_match, playlist scope
- "Custom similarity for energy/dance" -> weighted strategy, custom weights
Errors: Returns errors for missing source, missing scope_id, missing action params, genre_match with catalog, no genres, no matches, auth (401), permissions (403), rate limits (429).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds valuable behavioral context: it explains the tool's role as 'Centerpiece of the similarity engine,' details strategies and actions, lists error conditions (auth, permissions, rate limits), and describes return formats. This goes beyond annotations, though it doesn't fully explain idempotency or open-world implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, args, returns, examples, errors) and uses bullet points for readability. It's appropriately detailed for a complex tool, though some sentences could be more concise (e.g., the first paragraph has minor redundancy). Overall, it earns its length with valuable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple strategies, scopes, actions) and 0% schema description coverage, the description is highly complete: it explains purpose, parameters, return formats, examples, and error conditions. The output schema exists, so the description appropriately focuses on usage rather than repeating return structures. It provides all necessary context for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by detailing all parameters: it lists source types, 8 strategies with explanations, 5 scopes with requirements, 3 actions with dependencies, and additional parameters like limit, min_similarity, weights, and response_format. It provides semantic meaning (e.g., 'energy_match (workout)') that the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find tracks similar to a track, artist, or playlist using audio analysis or genre matching.' It specifies the verb ('find'), resources ('tracks'), and distinguishes from siblings by focusing on similarity matching rather than basic retrieval or playlist management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'For curated playlists, music discovery, and mood-based mixes.' It includes examples that show when to use specific configurations (e.g., 'Create workout playlist like this' for energy_match strategy) and mentions errors for misuse (e.g., 'genre_match with catalog'), helping the agent choose appropriate parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed audio analysis features for one or more Spotify tracks.
Retrieves sonic characteristics (energy, tempo, danceability, valence, acousticness, etc.)
that power the similarity engine. Supports batch processing of up to 100 tracks.
Args:
- track_ids: List of Spotify track IDs, 1-100 tracks
- response_format: 'markdown' or 'json' (default: JSON)
Returns:
Markdown: Per-track audio features (acousticness, danceability, energy, instrumentalness, liveness, loudness, speechiness, valence, tempo, key, mode, time_signature)
JSON: {"track_count": N, "features": [{id, acousticness, danceability, energy, instrumentalness, liveness, loudness, speechiness, valence, tempo, key, mode, time_signature, duration_ms, analysis_url, track_href, type, uri}]}
Examples:
- "Analyze the audio features of this track" -> Get sonic characteristics
- "What's the tempo and energy of these songs?" -> Extract specific features
Errors: Returns "No audio features available" if not found, or error for auth failure (401), rate limits (429). Note: Audio features endpoint deprecated for NEW apps (Nov 2024), but existing apps with extended mode access can still use it.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds valuable context beyond this: it specifies batch processing limits (up to 100 tracks), error handling (e.g., 'No audio features available', auth failure, rate limits), and a deprecation note for new apps. This enhances behavioral understanding without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, args, returns, examples, and errors, making it front-loaded and easy to scan. It is appropriately sized, but some parts like the detailed return formats could be slightly condensed. Overall, most sentences earn their place, though minor verbosity exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (batch processing, multiple output formats, deprecation notes) and the presence of an output schema (which covers return values), the description is complete enough. It includes purpose, usage examples, parameter details, error handling, and behavioral context, providing all necessary information for an agent to use the tool effectively without redundancy.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by detailing track_ids (list of 1-100 Spotify track IDs) and response_format (options and default). However, it does not fully explain the semantics of each parameter beyond what's implied, such as the format of track IDs or deeper meaning of response_format choices. Given the low schema coverage, the description adds some value but could be more comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'detailed audio analysis features for one or more Spotify tracks', specifying it retrieves sonic characteristics. It distinguishes from siblings like spotify_get_track (which gets track metadata) or spotify_find_similar_tracks (which finds recommendations), making the purpose specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use it (e.g., 'Analyze the audio features of this track' or 'What's the tempo and energy of these songs?'), but does not explicitly state when not to use it or name alternatives among siblings. It implies usage for batch processing of up to 100 tracks, which is helpful but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tracks from a specific Spotify playlist.
Retrieves tracks from a playlist with detailed information (artists, album, duration, IDs).
Results are paginated for large playlists.
Args:
- playlist_id: Spotify playlist ID (get from spotify_get_user_playlists or playlist URL)
- limit: Number of tracks to return, 1-50 (default: 20)
- offset: Starting position for pagination (default: 0)
- response_format: 'markdown' or 'json'
Returns:
Markdown: Numbered list with track details (name, artists, album, duration, ID, URI, popularity)
JSON: {"total": N, "count": N, "offset": N, "tracks": [{id, name, artists, album, duration_ms, popularity, uri, external_urls}], "has_more": bool}
Examples:
- "Show me what's in my workout playlist" -> View playlist contents
- "Get track IDs from this playlist" -> Extract IDs for operations
Errors: Returns "No tracks found" if empty, or error for invalid playlist (404), auth failure (401), rate limits (429).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds valuable behavioral context beyond annotations: pagination behavior, error conditions (404, 401, 429), and specific return formats. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose first, then parameters, returns, examples, and errors. Every section adds value, though the parameter documentation could be slightly more concise. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, rich annotations, and detailed description covering purpose, parameters, returns, examples, and errors, this is complete. The output schema exists, so the description appropriately focuses on format choices rather than duplicating return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides clear parameter documentation in the Args section with examples and defaults. However, it doesn't fully compensate for the schema gap by explaining parameter relationships or edge cases beyond what's already stated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'tracks from a specific Spotify playlist' with specific scope 'detailed information (artists, album, duration, IDs)' and distinguishes from siblings like spotify_get_track (single track) and spotify_get_user_playlists (list of playlists).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('Show me what's in my workout playlist', 'Get track IDs from this playlist') and mentions getting playlist_id from spotify_get_user_playlists, but doesn't explicitly state when NOT to use it or compare to all alternatives like spotify_search_tracks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get track recommendations from Spotify based on seed tracks, artists, or genres.
Generates personalized recommendations using up to 5 seeds (any combination) with
tunable audio features (energy, danceability, valence, tempo).
Args:
- seed_tracks/seed_artists/seed_genres: Up to 5 total seeds (track IDs, artist IDs, or genre names)
- limit: Results to return, 1-100 (default: 20)
- min/max/target audio features: Energy, danceability, valence (0.0-1.0), tempo (BPM)
- response_format: 'markdown' (formatted) or 'json' (structured data)
Returns:
Markdown: Numbered list with track details (name, artists, album, duration, ID, popularity)
JSON: {"total": N, "tracks": [{id, name, artists, album, duration_ms, popularity, uri, external_urls}]}
Examples:
- "Find energetic workout music" -> seed_genres=['electronic'], target_energy=0.9
- "Songs like this track" -> seed_tracks=['track_id']
- "Happy danceable songs" -> target_valence=0.8, target_danceability=0.8
Errors: Returns error for no seeds, >5 seeds, auth failure (401), rate limits (429), or no results.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior, but the description adds valuable context beyond this: it specifies error conditions (e.g., no seeds, >5 seeds, auth failure, rate limits), output formats, and example use cases, enhancing the agent's understanding without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, args, returns, examples, and errors, making it easy to scan. It is appropriately sized, but could be slightly more concise by avoiding repetition of parameter lists that are partially covered in the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, rich input schema, annotations, and output schema, the description is complete: it covers purpose, usage, parameters, return formats, examples, and errors, providing all necessary context for an agent to invoke the tool correctly without needing to rely solely on structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description compensates by explaining key parameters like seed types, limit, audio features, and response_format with examples. However, it does not cover all parameters (e.g., min/max/target for each audio feature are listed but not fully detailed), leaving some gaps in semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Get track recommendations') and resources ('from Spotify'), and distinguishes it from siblings by focusing on personalized recommendations based on seeds and audio features, unlike search or playlist tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (e.g., 'Find energetic workout music' or 'Songs like this track'), but does not explicitly state when not to use it or name alternatives among sibling tools, such as spotify_find_similar_tracks or spotify_search_tracks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific Spotify track by ID.
Retrieves comprehensive metadata for a single track including artists, album, duration,
popularity, URIs, and external URLs.
Args:
- track_id: Spotify track ID (not URI), extract from URIs or search results
- response_format: 'markdown' or 'json'
Returns:
Markdown: Track details (name, artists, album, duration, ID, URI, popularity)
JSON: Full API response (id, name, artists, album, duration_ms, popularity, uri, external_urls, preview_url, track_number, disc_number, explicit, available_markets)
Examples:
- "Get details for track ID 4u7EnebtmKWzUH433cf5Qv" -> Retrieve track info
- "Show me info about this track" -> When you have the track ID
Errors: Returns error for invalid track (404), auth failure (401), rate limits (429).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds valuable context beyond this: it specifies the tool retrieves comprehensive metadata, details the return formats (markdown vs. JSON), and lists potential errors (404, 401, 429). This enhances transparency about behavior and error handling, though it could mention rate limit specifics or auth requirements more explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, args, returns, examples, errors) and front-loaded key information. It is appropriately sized, but some sentences could be more concise (e.g., the examples are slightly verbose). Overall, it earns its place with efficient communication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, rich annotations, and the presence of an output schema (implied by returns section), the description is complete. It covers purpose, parameters, return formats, examples, and errors, providing all necessary context for an agent to use the tool effectively without needing to rely solely on structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full burden. It adds significant meaning: track_id is clarified as 'Spotify track ID (not URI), extract from URIs or search results', and response_format is explained with detailed output differences for 'markdown' vs. 'json'. This compensates well for the schema gap, though it doesn't cover all possible parameter nuances like length constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get detailed information') and resource ('about a specific Spotify track by ID'), distinguishing it from siblings like spotify_search_tracks (searching) or spotify_get_audio_features (audio analysis). It specifies it retrieves comprehensive metadata for a single track, making the purpose specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (e.g., 'When you have the track ID' in examples), but it does not explicitly mention when not to use it or name alternatives like spotify_search_tracks for finding tracks without an ID. The guidance is helpful but lacks explicit exclusions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of the current user's Spotify playlists.
Retrieves all playlists owned by or followed by the authenticated user. Results are
paginated. Use to browse playlists or find playlist IDs.
Args:
- limit: Number of playlists to return, 1-50 (default: 20)
- offset: Starting position for pagination (default: 0)
- response_format: 'markdown' or 'json'
Returns:
Markdown: List with playlist name, ID, track count, public status, description, URL
JSON: {"total": N, "count": N, "offset": N, "playlists": [{id, name, description, public, collaborative, tracks, owner, external_urls}], "has_more": bool}
Examples:
- "Show me my playlists" -> List all user playlists
- "Find my workout playlist" -> Browse to find specific one
- Need playlist ID -> Get ID from the list
Errors: Returns "No playlists found." if none exist, or error for auth failure (401), missing scopes (403), rate limits (429).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it explains pagination behavior, describes different return formats (markdown vs JSON), lists specific error conditions (auth failure, missing scopes, rate limits), and clarifies what happens when no playlists exist. While annotations cover safety (readOnlyHint=true, destructiveHint=false), the description provides practical implementation details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, args, returns, examples, errors) and front-loads the core functionality. Most sentences earn their place, though the examples section could be slightly more concise. Overall, it's appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, rich annotations, and comprehensive parameter documentation in the description, this is complete. The description covers purpose, usage, parameters, return formats, examples, and error conditions. With output schema available, it doesn't need to exhaustively document return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description fully compensates by documenting all three parameters with clear semantics: 'limit' with range and default, 'offset' with purpose and default, and 'response_format' with options and implications for output. It explains what each parameter controls and how they affect results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get a list'), resource ('current user's Spotify playlists'), and scope ('owned by or followed by'). It distinguishes this from siblings like spotify_get_playlist_tracks (which gets tracks within a playlist) and spotify_search_tracks (which searches for tracks).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('to browse playlists or find playlist IDs') and includes examples that illustrate use cases. However, it doesn't explicitly state when NOT to use it or name specific alternatives among siblings, though the examples imply differentiation from search-based tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for tracks on Spotify by name, artist, album, or keywords.
Searches Spotify's entire catalog using intelligent matching. Results ranked by relevance.
Args:
- query: Search text, 1-200 chars (e.g., "Bohemian Rhapsody", "artist:Queen", "album:...", or keywords)
- limit: Results to return, 1-50 (default: 20)
- offset: Starting position for pagination (default: 0)
- response_format: 'markdown' or 'json'
Returns:
Markdown: Search results with track details (name, artists, album, duration, ID, URI, popularity)
JSON: {"total": N, "count": N, "offset": N, "tracks": [{id, name, artists, album, duration_ms, popularity, uri, external_urls}], "has_more": bool}
Examples:
- "Find Bohemian Rhapsody by Queen" -> query="Bohemian Rhapsody Queen"
- "Search for songs by Taylor Swift" -> query="artist:Taylor Swift"
- "Look for indie rock songs" -> query="indie rock"
Errors: Returns "No tracks found" if no results, or error for auth failure (401), rate limits (429). Truncates if exceeds character limit.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond what annotations provide. While annotations cover read-only, open-world, and idempotent properties, the description adds specific details about result ranking ('ranked by relevance'), error conditions (auth failure, rate limits, 'No tracks found'), character truncation, and response format differences. This enhances the agent's understanding of how the tool behaves in practice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, args, returns, examples, errors) and front-loaded key information. While comprehensive, it could be slightly more concise by integrating some details more tightly, but every sentence adds meaningful value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (search functionality with multiple parameters and output formats), the description provides complete context. It covers purpose, parameters with semantics, return formats with examples, error handling, and behavioral details. With annotations covering safety properties and an output schema presumably detailing the return structure, the description fills all necessary gaps effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides extensive parameter semantics despite 0% schema description coverage. It explains each parameter's purpose, constraints, and defaults (query with examples and length limits, limit with range, offset for pagination, response_format with options). It also clarifies the relationship between parameters and output formats, adding significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Search for tracks') and resources ('Spotify's entire catalog'), distinguishing it from siblings like spotify_get_track (single track) or spotify_get_playlist_tracks (playlist-specific). It explicitly mentions searching by name, artist, album, or keywords.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool (searching Spotify's catalog with various query types) and includes examples that illustrate different use cases. However, it doesn't explicitly state when NOT to use it or mention specific alternatives among the sibling tools, such as spotify_find_similar_tracks for related tracks instead of keyword searches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose with no ambiguity. The tools cover specific operations like playlist management (create, add tracks, get tracks), track discovery (search, recommendations, similarity), and metadata retrieval (track info, audio features). The descriptions clearly differentiate their functions, making misselection unlikely.
All tool names follow a consistent 'spotify_verb_noun' pattern (e.g., spotify_create_playlist, spotify_get_track). The naming is uniform throughout, using snake_case with clear verbs like 'get', 'create', 'add', 'find', and 'search', making the tool set predictable and easy to navigate.
With 9 tools, the server is well-scoped for managing Spotify playlists and tracks. Each tool serves a distinct and necessary function, covering core operations from playlist creation and modification to track discovery and analysis. The count is appropriate for the domain without being overwhelming or insufficient.
The tool set provides comprehensive coverage for playlist and track management, including CRUD-like operations (create playlist, add tracks, get playlists/tracks) and advanced features (similarity, recommendations, audio analysis). A minor gap exists in playlist modification (e.g., no tool to remove tracks or update playlist details), but agents can work around this with the available tools.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Find independent music by how it sounds: similar tracks and playlists from a track link.
Accurate anime-song (anison) database for AI-built playlists — export to Spotify/Apple/YT Music
Spotify: Spotify Data API for Millions of songs & podcasts, artists, albums, playlists and more.
Full Spotify Web API coverage - albums, artists, playlists, player controls, and more.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/kylestratis/spotify-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
