imprvhub/mcp-claude-spotify

mcp-claude-spotify v0.4.1 - Critical Spotify API Adaptations and Stability Enhancements

Release Date: Tuesday, March 24, 2026
Status: Production Ready

Summary

This release, mcp-claude-spotify v0.4.1, is a crucial update focused on maintaining compatibility with recent and upcoming Spotify API changes, enhancing robustness in API interactions, and improving overall stability. With Spotify deprecating key endpoints, this version ensures continued functionality for playlist track retrieval, introduces more intelligent handling of diverse error responses, and fortifies input processing for AI models. This update is essential for uninterrupted and reliable Spotify integration.

Breaking Changes

Spotify API Deprecation: get-recommendations Tool Removed

FUNCTIONAL CHANGE: The get-recommendations tool has been entirely removed from mcp-claude-spotify.

• Impact: Users and AI models relying on the get-recommendations functionality will find this tool no longer available.
• Reasoning: Spotify deprecated the underlying get-recommendations endpoint as of November 2024, causing it to consistently return 404 errors. Its removal ensures that the toolset remains functional and relevant.
• Commit: 201bcfa (Part of #32)

Spotify API Endpoint Change: /playlists/{id}/tracks to /playlists/{id}/items

EXTERNAL API CHANGE: Spotify officially deprecated the /playlists/{id}/tracks endpoint in February 2026. This release adapts to this change by using the new /playlists/{id}/items endpoint.

• Impact: While mcp-claude-spotify automatically adapts to this change, direct integrations or custom tools that might have previously called the Spotify API using the /tracks endpoint will now need to use /items. This change is critical for maintaining playlist track retrieval functionality.
• Reasoning: Ensuring continued functionality for get-playlist-tracks in response to Spotify's API evolution.
• Commit: 201bcfa (Part of #32)

Major Features

Seamless Adaptation to Spotify API Changes

This release ensures mcp-claude-spotify remains fully functional despite recent Spotify API deprecations.

• Playlist Track Retrieval Continuity: The get-playlist-tracks tool now utilizes the new /playlists/{id}/items endpoint, guaranteeing that you can continue to retrieve tracks from Spotify playlists without interruption, even after the /playlists/{id}/tracks endpoint's deprecation.
• Commit: 201bcfa

Enhanced Robustness for AI Model Inputs

Improved handling of data types to prevent common issues with AI model outputs.

• Flexible Numeric Schema Handling: All numeric schema fields now explicitly use z.coerce.number(). This enhancement automatically converts numbers provided as strings by Large Language Models (LLMs) into their correct numeric type, significantly reducing potential data type errors and improving the reliability of tool execution.
• Commit: 201bcfa

Advanced Error Diagnostics

Better visibility into Spotify API responses for easier debugging and understanding of issues.

• Detailed Spotify Error Responses: Error messages now include the detailed Spotify error response body. This provides more context and actionable information when API requests fail, streamlining troubleshooting efforts.
• Commit: 201bcfa

Performance & Technical Improvements

Resilient Spotify API Request Handling

The core Spotify API request function has been strengthened to handle a broader range of error formats gracefully.

• Improved String Error Response Handling: The spotifyApiRequest utility now correctly handles non-object error data by using String() instead of JSON.stringify(). This prevents erroneous double-quoting of string-based error responses, ensuring clearer and more accurate error messages.
• Commit: 2e95bfc

Bug Fixes

• Spotify Playlist Track Endpoint: Addressed and fixed the issue caused by Spotify deprecating the /playlists/{id}/tracks endpoint by migrating to /playlists/{id}/items. (201bcfa)
• get-recommendations Functionality: Resolved consistent 404 errors by removing the deprecated get-recommendations tool. (201bcfa)
• LLM Numeric Input Coercion: Fixed instances where LLMs would send numbers as strings, causing validation or runtime errors, by implementing z.coerce.number(). (201bcfa)
• API Error Message Formatting: Corrected an issue where string error responses from the Spotify API were double-quoted, providing clearer and more accurate error output. (2e95bfc)

Refactors & Code Improvements

• Endpoint Update: Updated the get-playlist-tracks tool to use the new /playlists/{id}/items Spotify API endpoint. (201bcfa)
• Tool Removal: Removed the get-recommendations tool due to its deprecation and consistent 404 responses from the Spotify API. (201bcfa)

Documentation Updates

• Enhanced Error Messages: Improved clarity and detail in Spotify API error messages by including the full error response body. (201bcfa)

Migration Guide

For Users

1. get-recommendations Tool: Please note that the get-recommendations tool is no longer available due to Spotify API changes. Functionality relying on this tool will need to be re-evaluated.
2. Playlist Track Retrieval: The process for retrieving playlist tracks remains seamless. mcp-claude-spotify has automatically adapted to Spotify's new endpoint.

For Developers

1. Spotify API Endpoint: If you are directly interacting with the Spotify API for playlist tracks, update your calls from /playlists/{id}/tracks to /playlists/{id}/items. mcp-claude-spotify handles this internally for its own tools.
2. Tool Availability: The get-recommendations tool has been removed. Review any code or configurations that may have depended on its presence.
3. Error Handling: Note the improved error response details and string error handling. This may impact how you parse or display errors if you have custom error processing logic.

Known Limitations

• get-recommendations Absence: The get-recommendations feature is permanently removed, and there is no direct replacement within mcp-claude-spotify at this time due to Spotify's API changes.

Testing

• ✅ Spotify API Endpoint Update: Verified get-playlist-tracks functionality using the new /playlists/{id}/items endpoint. (201bcfa)
• ✅ get-top-tracks API Tests: New tests added for get-top-tracks API functionality to ensure correctness. (201bcfa)
• ✅ Numeric Schema Coercion: Tested z.coerce.number() implementation to ensure robust handling of string-based numeric inputs from LLMs. (201bcfa)
• ✅ Error Response Handling: Validated that detailed Spotify error response bodies are correctly included in error messages. (201bcfa)
• ✅ String Error Response Formatting: Confirmed spotifyApiRequest correctly formats non-object string error responses without double-quoting. (2e95bfc)

Acknowledgments

We extend our sincere thanks to @AnselmeSDR for the valuable contributions to this release, including critical fixes for Spotify API adaptations and robust error handling.

Support & Feedback

For issues or suggestions, please create a new issue in the GitHub repository.

Release Authorization

Approved by: Iván Luna
Architecture Review: Complete
Security Audit: Passed
Performance Testing: Validated

This release significantly fortifies mcp-claude-spotify against external API changes, ensuring a more stable and reliable experience for all users and integrations.

Full Changelog: https://github.com/imprvhub/mcp-claude-spotify/compare/0.4.0...0.4.1