Spotify Control Agent via Model Context Protocol (MCP)

This repository furnishes an implementation of an MCP (Model Context Protocol) backend designed to interface with and command the Spotify application. Users can employ an MCP-compatible client, such as Cursor or Claude for Desktop (compatible with both macOS and Windows), to issue instructions.

Capabilities Exposed

This service exposes the following discrete functions:

• play: To initiate playback of a specified track, album, or playlist, or to resume a paused session.
• pause: To halt the current audio stream.
• next: To advance to the subsequent item in the queue or playlist.
• previous: To revert to the preceding track.
• get_current_track: To retrieve metadata regarding the currently active playback item.
• search: To query the Spotify catalog for music, albums, artists, or curated lists.

Prerequisites for Operation

To successfully deploy and operate this controller, the following dependencies are mandatory:

• The Bun runtime (version 1.0.0 or newer).
• An active Spotify Premium subscription.
• A registered Spotify Developer Application:
  • Register an application via the Spotify Developer Dashboard.
  • Secure and retain the unique Client ID and Client Secret.
  • Ensure the URI http://localhost:8888/callback is registered under the Redirect URIs within your application's configuration.
• An accessible MCP client application (e.g., Cursor or Claude for Desktop).

Setup Procedure

Follow these steps to prepare the environment:

1. Repository Cloning:

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

2. Dependency Resolution:

   bash bun install

3. Environment Variable File Creation:

   In the project's root directory, instantiate a file named .env. Populate it with your Spotify credentials:

   SPOTIFY_CLIENT_ID=your_spotify_client_id SPOTIFY_CLIENT_SECRET=your_spotify_client_secret SPOTIFY_REDIRECT_URI=http://localhost:8888/callback

   Authorization tokens will be populated here by the setup script:

   SPOTIFY_ACCESS_TOKEN= SPOTIFY_REFRESH_TOKEN=

4. Token Acquisition Script Execution:

   This command launches a browser flow to authorize the application, fetching the necessary initial authorization and refresh tokens.

   bash bun run auth

   After execution, the script outputs the retrieved SPOTIFY_ACCESS_TOKEN and SPOTIFY_REFRESH_TOKEN. Transfer these values into your .env file.

5. MCP Client Configuration:

   Configure your chosen MCP client to recognize this service. Note: Always substitute the placeholder paths below with the actual, fully qualified absolute path to your spotify-mcp directory.

   • For Cursor Users:

     • Access Cursor Settings (Cmd+, or Ctrl+,).
     • Search for "Model Context Protocol".
     • Select "Edit in settings.json".

     • Integrate the following structure into the mcp.servers list:

       { "mcp.servers": [ { "spotify": { "command": "bun", "args": ["/absolute/path/to/your/spotify-mcp/src/index.ts"], "env": { "SPOTIFY_CLIENT_ID": "your_spotify_client_id", "SPOTIFY_CLIENT_SECRET": "your_spotify_client_secret", "SPOTIFY_REDIRECT_URI": "http://localhost:8888/callback", "SPOTIFY_ACCESS_TOKEN": "your_spotify_access_token", "SPOTIFY_REFRESH_TOKEN": "your_spotify_refresh_token" } } } ] }

       Best Practice: Avoid hardcoding credentials in settings.json; rely on the environment variables defined in your separate .env file.

   • For Claude for Desktop (macOS/Windows):

     • Locate the configuration file:
       • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
       • Windows: %APPDATA%\Claude\claude_desktop_config.json

     • Add the following configuration to the top-level mcpServers object:

       { "mcpServers": { "spotify": { "command": "bun", "args": ["/absolute/path/to/your/spotify-mcp/src/index.ts"] } } }

       Best Practice: Prefer using the .env file mechanism over embedding sensitive variables directly in the configuration file.

   Crucial Note: The configuration for your MCP client must utilize fully qualified, absolute filesystem paths.

6. Client Relaunch:

Ensure you fully restart your MCP client (Cursor or Claude) for the updated configuration to take effect.

Initiating the Control Server

Execute the following command to launch the service. It is configured for automatic script reloading upon source code modification (leveraging Bun's watch capability):

bash bun run start

Keep this terminal session active while you are actively using the controller functionality.

Operational Examples

Once the server is active and the client is configured, you can issue commands naturally:

"Start playing Bohemian Rhapsody"

"Suspend playback"

"Identify the currently audible track"

"Locate albums by Taylor Swift"

"Advance to the next song"

"Initiate playback of spotify:track:4uLU6hMCjMI75M1A2tKUQC"

WIKIPEDIA: XMLHttpRequest (XHR) defines a JavaScript object API facilitating the transmission of HTTP requests from a web browser to a remote server. Its methods permit browser-based applications to dispatch requests post-page-load and retrieve subsequent data asynchronously. XHR is foundational to Ajax methodologies. Before its introduction, server interaction primarily relied on traditional hyperlinks or form submissions, frequently resulting in the complete replacement of the current webpage view.

== Chronology of Development == The foundational concept for XMLHttpRequest originated around 2000, conceived by developers working on Microsoft Outlook. This idea was subsequently realized within the Internet Explorer 5 browser release (1999). However, the initial implementation did not use the identifier XMLHttpRequest; instead, developers employed object instantiations like ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 (2006) was released, universal browser support for the standard XMLHttpRequest identifier was established. Subsequent browser engines adopted this standard: Mozilla's Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005), solidifying XMLHttpRequest as the cross-browser norm.

=== Standardization Efforts === The World Wide Web Consortium (W3C) published the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. This was followed by a Level 2 Working Draft specification released on February 25, 2008. Level 2 enhancements introduced functionality for tracking request progress, enabling cross-site data transfer, and handling raw byte streams. By the close of 2011, the Level 2 features were formally integrated back into the primary specification. Development responsibility transitioned to the WHATWG organization near the end of 2012, which now maintains the document as a continuously evolving resource using Web IDL notation.

== Operational Use Cases == General utilization of XMLHttpRequest involves a sequence of programming actions.

1. Instantiation: Create an XMLHttpRequest object via its constructor:
2. Configuration: Invoke the "open" method to define the request method (GET/POST, etc.), specify the target resource URL, and determine whether the operation will be synchronous or asynchronous:
3. Asynchronous Listener Setup: For asynchronous operations, establish an event handler function to execute when the request state transitions:
4. Transmission: Start the network operation by calling the "send" method (optionally providing data for POST requests):
5. Response Handling: Monitor state changes via the event listener. Upon receiving server data, it is typically accessible in the "responseText" property. The object signals completion by transitioning to state 4, designated as the "done" state. Beyond these core steps, XMLHttpRequest offers extensive control over request transmission parameters and response parsing. Custom HTTP headers can be appended to guide server behavior. Data can be uploaded to the server within the send call. The server's JSON response can be parsed directly into a usable JavaScript object, or streamed for incremental processing. Furthermore, requests can be intentionally terminated early or assigned timeout parameters.

== Cross-Origin Communication Issues == In the nascent stages of the World Wide Web, limitations were recognized regarding the ability to breach sec