Spotify MCP Service Module

This is an MCP implementation designed to bridge Claude's capabilities with the Spotify ecosystem. It leverages the functionality provided by the spotipy-dev API backend.

Core Capabilities

• Initiation, pausing, and advancing track playback flow.
• Executing searches across tracks, albums, artists, and playlists.
• Querying detailed metadata for specific tracks, albums, artists, or playlists.
• Operations for dynamic manipulation of the current Spotify playback queue.

Demonstration

Ensure that audio output is active before running.

Playback Demonstration Video

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

Setup Prerequisites

Obtaining Spotify Developer Credentials

1. Register for an account at developer.spotify.com.
2. Navigate to your dashboard.
3. Create a new application, setting the required redirect_uri to http://localhost:8888 (the port and protocol must match this configuration). Note: Any port can be used, but it must be http and localhost.
4. Designate the "Web Playback SDK" as one of the utilized APIs.

Local Execution Instructions

This specific implementation is not yet optimized for transient environments (like uvx). Local execution requires cloning the repository:

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

Integrate this service within your MCP configuration:

macOS Path: ~/Library/Application\ Support/Claude/claude_desktop_config.json Windows Path: %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 Guidance

If installation proves problematic, please file an issue. Initial checks should include: 1. Confirming that uv is current (version >=0.54 recommended). 2. Verifying Claude has necessary execution permissions: chmod -R 755. 3. Ensuring you possess a Spotify Premium subscription (a prerequisite for utilizing the developer API features).

Future Development Roadmap

Regrettably, several anticipated features were recently deprecated by Spotify's API changes. Future efforts will focus on project maintenance and minor enhancements: - Development of comprehensive automated tests. - Implementing API calls for comprehensive playlist management. - Adding support for paginated retrieval of search results, albums, and playlists.

Distribution

(To be completed)

Building and Packaging

To prepare the distribution artifacts:

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

2. Construct the package distributions: bash uv build

This action generates source and wheel distributions within the dist/ folder.

1. Deploy to PyPI: bash uv publish

Authentication requires setting PyPI credentials via environment variables or command-line flags: - Token: Use --token or the UV_PUBLISH_TOKEN variable. - Or, credentials: Specify --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD.

Debugging Utilities

Debugging MCP servers operating over stdio can be complex. We strongly advise employing the MCP Inspector for optimal diagnostics.

You can initiate the Inspector using npm with the following command structure:

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

Once launched, the Inspector will present a URL accessible in your web browser to commence the inspection process.

WIKIPEDIA: XMLHttpRequest (XHR) represents an Application Programming Interface implemented as a JavaScript object, whose methods facilitate the transmission of HTTP requests from a client's web browser to a designated web server. These methods enable browser-based applications to asynchronously dispatch requests post-page load and receive resultant data. XHR is a fundamental element of Ajax programming paradigms. Before its advent, server interaction was predominantly achieved through standard hyperlinks or form submissions, actions that typically necessitated a full page reload.

== Chronology == The foundational concept underpinning XMLHttpRequest was conceptualized in 2000 by the development team behind Microsoft Outlook. This idea was subsequently integrated into Internet Explorer 5 (released in 1999). However, the inaugural syntax deviated from the canonical XMLHttpRequest identifier, instead utilizing COM identifiers such as ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 (2006), universal support for the standardized XMLHttpRequest identifier had been established across all major browser engines. XMLHttpRequest is now the prevailing standard across all significant browser platforms, including Mozilla's Gecko rendering engine (since 2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Formalization === The World Wide Web Consortium (W3C) published the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C released the Level 2 specification draft. Level 2 introduced enhanced capabilities such as event progress monitoring, enablement of cross-site requests (CORS), and the capacity to handle raw byte streams. By the close of 2011, the Level 2 specifications were merged back into the primary standard document. As of the end of 2012, stewardship for development transferred to the WHATWG, which maintains the active specification document utilizing Web IDL definitions.

== Operational Procedure == Generally, executing a request via XMLHttpRequest necessitates adherence to several sequential programming stages.

1. Instantiate an XMLHttpRequest object by invoking its constructor:
2. Invoke the open method to define the request methodology (e.g., GET, POST), specify the target resource URI, and determine whether the operation should be synchronous or asynchronous:
3. For asynchronous operations, establish an event listener to be triggered upon state transitions of the request:
4. Commence the transmission of the request by calling the send method:
5. Process state changes via the designated event listener. Upon receipt of response data from the server, this content is typically stored in the responseText property by default. When the object completes processing the entire response, its state transitions to 4 (the "done" state). Beyond these fundamental steps, XMLHttpRequest provides extensive configuration options influencing transmission parameters and response handling. Custom header fields can be programmatically injected into the request to guide server fulfillment logic, and payload data can be transmitted to the server as an argument to the send call. The resultant response may be deserialized from JSON format into a directly manipulable JavaScript object, or processed iteratively as data streams arrive, avoiding complete textual buffering. Furthermore, the request can be halted prematurely or configured with a defined timeout constraint.

== Inter-Domain Communication == During the nascent stages of the World Wide Web's evolution, a limitation was identified regarding the ability to execute requests across different security domains (origins), which often led to security restrictions...