spotify-mcp Modular Control Protocol Server

This MCP implementation establishes a robust bridge between the Claude conversational AI and the Spotify ecosystem. It leverages the capabilities of the spotipy-dev API wrapper.

Core Capabilities

• Control playback state: initiation, pausing, and track advancement.
• Comprehensive search across music assets: tracks, albums, artists, and curated playlists.
• Retrieval of detailed metadata for any specified track, album, artist, or playlist entity.
• Manipulation and management of the active Spotify playback queue.

Demonstration

Ensure an active audio output device is connected prior to execution.

Visual Example

https://github.com/user-attachments/assets/20ee1f92-f3e3-4dfa-b945-ca57bc1e0894

Setup Prerequisites

Obtaining Spotify Developer Credentials

Register an application via the Spotify Developer portal. Access your credentials from the dashboard. When creating the application, set the redirect_uri to precisely http://localhost:8888 (local host and HTTP are mandatory; the port number is flexible). Explicitly enable 'Web Playback SDK' under 'APIs used'.

Local Execution Environment

This project is not currently configured for immediate deployment in ephemeral execution contexts (e.g., immediate uvx usage). Local setup requires cloning the repository:

bash git clone https://github.com/varunneal/spotify-mcp.git

Integrate this tool as an MCP server by updating your configuration file:

On macOS systems: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows systems: %APPDATA%/Claude/claude_desktop_config.json

"spotify": { "command": "uv", "args": [ "--directory", "/path/to/spotify_mcp", "run", "spotify-mcp" ], "env": { "SPOTIFY_CLIENT_ID": YOUR_CLIENT_ID, "SPOTIFY_CLIENT_SECRET": YOUR_CLIENT_SECRET, "SPOTIFY_REDIRECT_URI": "http://localhost:8888" } }

Troubleshooting Assistance

If initialization fails, please file a bug report. Initial diagnostic tips include: 1. Verify that the uv version is current; minimum requirement is >=0.54. 2. Confirm that the project directory possesses adequate execution permissions: chmod -R 755. 3. A Spotify Premium subscription is prerequisite for utilizing the developer API features.

Logs emitted by this MCP server (per the specification) are directed to standard error. On macOS, the Claude Desktop application routes these to ~/Library/Logs/Claude. For other operating systems, consult the documentation at https://modelcontextprotocol.io/quickstart/user#getting-logs-from-claude-for-desktop.

Future Development Roadmap

Regrettably, several proposed functionalities have been retired due to recent deprecations in Spotify's recommendation APIs. Future enhancements will concentrate on essential maintenance or core quality-of-life improvements: - Implementation of unit and integration tests. - Extending API coverage to facilitate playlist administration. - Incorporating logic to handle paginated responses for search results and large playlists/albums.

Contributions via Pull Requests are highly encouraged!

Distribution

(Work in progress)

Package Generation and Upload

To prepare the distribution artifacts:

1. Synchronize dependencies and refresh the lock file: bash uv sync

2. Compile package artifacts (source and wheel formats): bash uv build

This action populates the dist/ directory.

1. Submit the package to PyPI: bash uv publish

Authentication for PyPI requires either a token provided via the --token flag or the UV_PUBLISH_TOKEN environment variable, or by specifying credentials via --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD.

Debugging Overhead

Debugging MCP servers running over stdio presents inherent difficulties. We strongly advise employing the MCP Inspector tool for optimal diagnostics.

Launch the Inspector using npm (ensure Node.js/npm is installed):

bash npx @modelcontextprotocol/inspector uv --directory /Users/varun/Documents/Python/spotify_mcp run spotify-mcp

Once initiated, the Inspector will present a localized URL where you can connect your browser to monitor and debug the communication flow.

== WIKIPEDIA SUPPLEMENT: XMLHttpRequest Context == XMLHttpRequest (XHR) defines a JavaScript object interface used to dispatch HTTP requests from a web browser to a server. This interface permits client-side applications to fetch or post data to a server post-page-load, facilitating dynamic updates. XHR is foundational to Ajax methodologies. Before Ajax, server interaction was predominantly achieved via traditional hyperlink navigation or form submissions, which typically resulted in a full page reload.

== Chronology == The conceptual basis for XMLHttpRequest originated around 2000 with Microsoft Outlook development efforts. This concept was first integrated into Internet Explorer 5 (1999). However, the initial implementation utilized COM object identifiers such as ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP") rather than the standardized XMLHttpRequest string. By Internet Explorer 7 (2006), support for the standardized identifier was universal across major browser engines, including Mozilla’s Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005). XMLHttpRequest is now the established convention across all leading web browsers.

=== Standardization Trajectory === The World Wide Web Consortium (W3C) released an initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A Level 2 specification followed on February 25, 2008, introducing capabilities for event progress monitoring, facilitating cross-site access, and managing byte streams. By the conclusion of 2011, the Level 2 features were merged back into the primary specification document. In late 2012, development stewardship transitioned to the WHATWG, which maintains the document as a living standard defined using Web IDL.

== Operational Procedure == Executing a request via XMLHttpRequest generally involves a sequence of programming steps:

1. Instantiate an XMLHttpRequest object via its constructor.
2. Invoke the open() method to define the request methodology (e.g., GET/POST), specify the target URI, and select between synchronous or asynchronous execution.
3. For asynchronous requests, attach an event listener function that will trigger upon state changes.
4. Initiate the transmission by calling the send() method, potentially including payload data.
5. Monitor state transitions within the assigned event listener. Upon receiving a response, the data is typically accessible in the responseText property once the state reaches 4 ("done"). Beyond these essentials, XHR offers extensive controls over request transmission and response handling. Custom request headers can be injected to instruct the server on processing. Data payloads can be uploaded within the send() call. Responses can be parsed directly from JSON into native JavaScript objects, or processed iteratively as chunks arrive instead of waiting for completion. Furthermore, requests can be halted prematurely or subjected to a defined timeout limit.

== Inter-domain Communication Restrictions == During the initial expansion of the World Wide Web, limitations were quickly identified regarding the possibility of executing requests across different security domains, leading to the implementation of the same-origin policy.