Spotify Model Context Protocol (MCP) Interface Server

This repository furnishes an implementation of a Model Context Protocol (MCP) endpoint, specifically designed to interface with the Spotify Web API. This setup enables users to issue high-level, natural language directives to manage their current music listening experience through an authorized MCP consumer application, such as Cursor or Claude for Desktop on supported operating systems.

Exposed Functionality

This service registers the following discrete operations accessible via the MCP framework:

• play: Initiate playback of a specified media item (e.g., a song, compilation, or artist's catalog) or resume a previously stopped session.
• pause: Suspend the currently active audio stream.
• next: Transition immediately to the subsequent item in the current queue or album.
• previous: Return to the preceding audio item.
• get_current_track: Retrieve metadata detailing the audio content presently being reproduced.
• search: Execute queries against the Spotify catalog to locate specific artists, albums, tracks, or playlists.

System Requirements

To successfully deploy and operate this control layer, the following prerequisites must be satisfied:

• Runtime Environment: Bun package manager (version 1.0.0 or newer).
• Spotify Account Status: An active subscription to Spotify Premium is mandatory.
• Developer Registration: A registered application within the Spotify Developer Dashboard. Key artifacts required are the Client Identifier and the Client Secret. Crucially, the Redirect URI must be configured to include http://localhost:8888/callback within the application settings.
• Client Application: An installed and configured MCP-compatible client (e.g., Cursor, Claude for Desktop).

Deployment and Configuration Guide

1. Source Code Acquisition:

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

2. Dependency Resolution:

   bash bun install

3. Environment Variable File Creation:

   Establish a file named .env in the project's root directory and 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

   Token placeholders, populated post-authentication:

   SPOTIFY_ACCESS_TOKEN= SPOTIFY_REFRESH_TOKEN=

4. Authentication Flow Execution:

   Run the dedicated setup script to initiate the OAuth process. This action launches a browser window prompting Spotify login and authorization, subsequently outputting the necessary token pair to the console for manual .env file updating.

   bash bun run auth

5. MCP Client Integration:

   • Cursor Integration Steps:

     • Navigate to Cursor settings (Cmd+, or Ctrl+,).
     • Search for "Model Context Protocol".
     • Select the option to edit settings.json.

     • Append the necessary configuration block to the mcp.servers list. Note: Substitute /absolute/path/to/your/spotify-mcp with the fully qualified, absolute directory path to your project clone.

       { "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 Advisory: Externalizing credentials to the .env file is strongly preferred over embedding them directly in settings.json.

   • Claude for Desktop Configuration (macOS/Windows):

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

     • Integrate the following structure into the mcpServers object, again using the absolute path to the project directory:

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

       Best Practice Advisory: Utilizing the external .env file for sensitive parameters is recommended over direct inclusion in claude_desktop_config.json.

   • Critical Instruction: Absolute path specification is mandatory across all client configuration methods.

6. Client Application Restart

Ensure the host MCP client (Cursor or Claude) is fully relaunched to incorporate the new server definition.

Server Initiation

Execute the following command to launch the control server, which includes watch-mode functionality via Bun for automatic restarts upon code modification:

bash bun run start

Maintain this terminal session active throughout the operational period.

Operational Examples

Once the server is active and the client is configured, interaction proceeds via conversational prompts. Examples include:

"Initiate playback of Bohemian Rhapsody"

"Halt the current audio stream"

"Query the name of the currently active track"

"Locate discographies by Taylor Swift"

"Advance to the next selection"

"Execute playback using URI: spotify:track:4uLU6hMCjMI75M1A2tKUQC"