Spotify Audio Orchestration Module (MCP)

This Model Context Protocol (MCP) implementation bridges the capabilities of Claude AI with the Spotify music service ecosystem. It leverages the robust underlying architecture established by the spotipy-dev API library.

Core Functionalities

• Initiate, suspend, and advance the current playback stream.
• Perform detailed searches across tracks, complete albums, artist entities, and curated playlists.
• Retrieve comprehensive metadata for any specific track, album, artist, or playlist resource.
• Administer and modify the contents of the active Spotify playback queue.

Demonstration

Ensure that audio output is currently active on your Spotify client.

Visual Example

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

Setup and Authentication

Acquiring Spotify Developer Credentials

1. Establish an account via the Spotify Developer portal.
2. Navigate to the Application Dashboard.
3. Register a new application. Crucially, set the redirect_uri parameter to http://localhost:8888 (or an alternative port using http:// protocol on localhost).
4. Specify that the application utilizes the "Web Playback SDK" among the APIs selected.

Local Execution Instructions

This module is presently not optimized for ephemeral runtime environments (e.g., immediate uvx deployment). Local setup requires cloning the repository:

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

Integrate this tool by configuring it as an MCP server within your Claude configuration file:

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

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 integration proves difficult, please report an issue. Preliminary troubleshooting suggestions include: 1. Verification that the uv utility is current, preferably version >=0.54. 2. Confirmation that the Claude process possesses execution permissions for the repository: chmod -R 755. 3. Requirement for an active Spotify Premium subscription (necessary for API developer functionality).

Logging output from this MCP server is directed to standard error (stderr) as defined by the MCP specification. On macOS, the Claude Desktop application typically routes these messages to ~/Library/Logs/Claude. For other operating systems, refer to the standard logging documentation: https://modelcontextprotocol.io/quickstart/user#getting-logs-from-claude-for-desktop.

Future Development Roadmap (TODO)

Due to recent changes restricting access to several recommendation features within the Spotify API (reference article), future enhancements will focus on maintenance and core functionality expansion: - Integration of unit tests. - Implementing API support for playlist manipulation. - Enhancing search and playlist retrieval to handle paginated results.

Contributions (Pull Requests) are highly encouraged!

Distribution Process

(To be filled)

Package Creation and Publishing Steps

To finalize the package for official release distribution:

1. Synchronize dependencies and refresh the lock file:

uv sync

1. Generate distribution archives (source and wheel):

uv build

This action populates the dist/ directory.

1. Upload to the PyPI repository:

uv publish

Note: PyPI authentication requires specifying credentials either via command-line flags (e.g., --token or using UV_PUBLISH_TOKEN) or standard username/password flags (--username/--password or corresponding environment variables).

Debugging Utilities

Debugging MCP servers running over standard I/O streams presents unique challenges. We strongly recommend utilizing the MCP Inspector tool for an optimized debugging workflow.

You can launch the Inspector by invoking npm (Node Package Manager) using the following command structure:

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

Once initiated, the Inspector interface will provide a URL accessible via a web browser to begin the inspection and debugging session.