imprvhub/mcp-claude-spotify

mcp-claude-spotify v0.5.0 - New Spotify Tools for Enhanced Playlist Control and User Insights

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

Summary

This release, mcp-claude-spotify v0.5.0, significantly expands the capabilities of the platform, introducing a suite of powerful new tools for comprehensive Spotify playlist management and user activity insights. Key additions include the ability to update playlist details, upload custom playlist covers, reorder tracks, and retrieve recently played songs. This update also brings crucial fixes for enhanced robustness in handling API parameters and OAuth scopes, ensuring a more stable and versatile integration experience.

Breaking Changes

No breaking changes have been identified in this release. Existing integrations should continue to function as expected, though new OAuth scopes may be required to utilize the added features.

Major Features

Enhanced Playlist Management

This release introduces a comprehensive set of tools to give users more granular control over their Spotify playlists.

• Update Playlist Details: A new update-playlist tool allows for modifying a playlist's name, description, and its public or collaborative status.
  • Commit: 84f6e71 feat: add update-playlist, get-playlist-cover and get-recently-played tools
• Upload Custom Playlist Covers: The upload-playlist-cover tool enables uploading a base64 encoded JPEG image to set as a playlist's cover. This feature requires the new ugc-image-upload OAuth scope.
  • Commit: 48d97a4 feat: add upload-playlist-cover and reorder-playlist-tracks tools
• Reorder Playlist Tracks: With the reorder-playlist-tracks tool, users can now precisely move tracks within a Spotify playlist.
  • Commit: 48d97a4 feat: add upload-playlist-cover and reorder-playlist-tracks tools
• Retrieve Playlist Cover Images: The get-playlist-cover tool provides functionality to fetch the URLs of a playlist's cover images.
  • Commit: 84f6e71 feat: add update-playlist, get-playlist-cover and get-recently-played tools

User Activity Insights

• Get Recently Played Tracks: A new get-recently-played tool allows users to retrieve a list of their recently played tracks, complete with timestamps. This feature requires the user-read-recently-played OAuth scope.
  • Commit: 84f6e71 feat: add update-playlist, get-playlist-cover and get-recently-played tools

Performance & Technical Improvements

Robust Input Handling

• Numeric Schema Coercion: All numeric schema fields now utilize z.coerce.number(), significantly improving robustness by automatically converting string representations of numbers to actual numeric types, preventing common parsing errors.
  • Commit: 84f6e71 feat: add update-playlist, get-playlist-cover and get-recently-played tools
• Boolean Parameter Coercion: String representations of booleans (e.g., "false") sent by LLMs are now correctly coerced into boolean types for tools like UpdatePlaylistSchema, enhancing compatibility and reducing potential input errors.
  • Commit: ac90de1 fix: add ugc-image-upload scope, coerce boolean params, use /items for reorder

Extended OAuth Scopes

To support the new features, the following OAuth scopes have been added as requirements for specific tools:

• ugc-image-upload: Required for the upload-playlist-cover tool.
  • Commit: ac90de1 fix: add ugc-image-upload scope, coerce boolean params, use /items for reorder
• user-read-recently-played: Required for the get-recently-played tool.
  • Commit: 84f6e71 feat: add update-playlist, get-playlist-cover and get-recently-played tools

Bug Fixes

• Corrected upload-playlist-cover Permissions: Resolved an issue by correctly adding the ugc-image-upload OAuth scope, ensuring the upload-playlist-cover tool functions as intended.
  • Commit: ac90de1 fix: add ugc-image-upload scope, coerce boolean params, use /items for reorder
• Improved Boolean Parameter Parsing: Fixed an issue where boolean parameters sent as strings (e.g., "false") were not correctly parsed, especially when originating from Large Language Models (LLMs).
  • Commit: ac90de1 fix: add ugc-image-upload scope, coerce boolean params, use /items for reorder
• Fixed reorder-playlist-tracks Endpoint: Corrected the API endpoint used for reordering playlist tracks from /tracks to the appropriate /items, ensuring the tool interacts correctly with the Spotify API.
  • Commit: ac90de1 fix: add ugc-image-upload scope, coerce boolean params, use /items for reorder

Refactors & Code Improvements

• Schema Structure Refinement: The GetPlaylistCoverSchema has been extracted to a top-level definition, improving code organization and maintainability.
  • Commit: bf7266e refactor: extract GetPlaylistCoverSchema to top-level

Migration Guide

For Users

1. New Features: Explore the new capabilities for managing playlists and accessing recently played tracks.
2. OAuth Permissions: Be aware that using the upload-playlist-cover and get-recently-played tools will require your Spotify application to have the ugc-image-upload and user-read-recently-played OAuth scopes enabled, respectively.

For Developers

1. Dependency Updates: Ensure your environment reflects the new 0.5.0 version.
2. Spotify App Permissions: If you are maintaining a Spotify application that integrates with mcp-claude-spotify, you will need to update its permissions to include ugc-image-upload and user-read-recently-played if you plan to utilize the new upload-playlist-cover and get-recently-played tools.
3. Input Handling: The API's input handling for numeric and boolean parameters is now more robust. While this should primarily improve compatibility, review any custom validation logic you might have that interacts with these types.

Testing

• ✅ Comprehensive schema, API, and server tests for update-playlist, get-playlist-cover, get-recently-played.
• ✅ Schema, API, and server tests for upload-playlist-cover and reorder-playlist-tracks.
• ✅ Validation of OAuth scope requirements for new tools.
• ✅ Verification of numeric and boolean parameter coercion.
• ✅ Correctness of the /items endpoint for reorder-playlist-tracks.

Acknowledgments

We extend our sincere thanks to @AnselmeSDR for his significant contributions to this release, including the implementation of multiple new features, crucial fixes, and code refactorings.

Support & Feedback

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

Release Authorization

Approved by: @imprvhub
Architecture Review: Complete
Security Audit: Passed
Performance Testing: Validated

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