mcp-claude-spotify

MCP Claude Spotify is an integration tool that lets Claude Desktop interact with Spotify through the Model Context Protocol (MCP), developed by imprvhub and open-sourced on GitHub.

Purpose

The tool is designed to connect Spotify's music service capabilities to Claude Desktop, enabling users to complete operations such as music search, playback control, playlist management, and listening history queries through natural language instructions. It is suitable for users who want to operate Spotify directly within Claude, for example organizing playlists, finding specific tracks, or viewing personal listening habits.

Main Capabilities

• Spotify Authentication: Supports authorizing a Spotify account through the OAuth flow, with the token saved to ~/.spotify-mcp/tokens.json in the user directory for persistence.
• Search Functionality: Can search tracks, albums, artists, and playlists, with support for specifying the number of results returned.
• Playback Control: Get the current playback state, play specified tracks (optionally specifying a device), pause, and skip tracks (next/previous).
• Playlist Management: Get the user's list of playlists, create new playlists, update the name, description, public/private status, and collaborative settings, unfollow (remove) playlists, retrieve tracks within a playlist with pagination, add or remove tracks, reorder tracks, and get and upload custom cover images (requires base64-encoded JPEG, maximum 256KB).
• Discovery and History: Get the user's most-played tracks over different time ranges (approximately the last 4 weeks, 6 months, or several years), as well as recently played track records.

Usage

Before use, the following are required: Node.js 20 or higher, a Spotify account, and Spotify API credentials (Client ID and Client Secret). It can be installed automatically to Claude Desktop via Smithery, or by manually cloning the repository, installing dependencies, and building the project. You need to create an app in the Spotify Developer Dashboard and set the redirect URI to http://127.0.0.1:8888/callback, and obtain the Client ID and Client Secret. Then edit the Claude Desktop configuration file (on macOS, ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows, %APPDATA%\Claude\claude_desktop_config.json), add a spotify configuration section, and fill in the absolute path and credentials. For first-time authentication, you can run the server in the terminal and set SPOTIFY_AUTO_AUTH=true to complete browser authorization, or use the auth-spotify command in Claude. After successful authentication, Claude Desktop needs to be restarted.

Applicable Scenarios

• Quickly search for and play music through Claude.
• Organize and edit Spotify playlists (add, delete, sort, modify information).
• Query personal listening history and top tracks.
• Manage Spotify operations uniformly within Claude, without switching applications.

Limitations and Notes

• Version 0.6.0 has removed the get-recommendations tool, because Spotify deprecated /v1/recommendations and related endpoints (related-artists, audio-features, audio-analysis, featured-playlists, and 30-second preview URLs) on November 27, 2024. Apps created after this date will return 403 Forbidden, and apps in development mode also lose access. It is recommended to use search-spotify and get-top-tracks.
• The authentication flow is now CSRF-protected, and the login URL carries a random state value; the token file is stored with 600 permissions in a 700 directory; the callback only listens on 127.0.0.1; if port 8888 is in use, the server reports it and stops, and will not forcibly terminate other processes.
• IDs in tool parameters are validated, and only pure Spotify IDs are accepted.
• Common issues include the "Server disconnected" error, the browser not opening automatically, authentication errors, server startup errors, and the tool not appearing in Claude. Check the configuration, port, and Node.js version, etc.
• Never share the Client ID and Client Secret.
• The project includes Jest-based automated tests covering Zod schema validation, Spotify API interactions, and MCP server functionality.