mcp-claude-spotify

This MCP server enables Claude Desktop to interact with Spotify through the Model Context Protocol (MCP). It authenticates with Spotify, exposes search capabilities for tracks, albums, artists, and playlists, and provides playback controls (play, pause, next, previous). It also supports creating and managing playlists, retrieving personalized recommendations, and accessing a user’s top tracks over different time ranges. After the MCP server is running, Claude Desktop can invoke the Spotify MCP endpoints to perform actions on behalf of the user, streamlining music discovery and playback from within Claude’s interface.

To use it, first ensure you have valid Spotify API credentials and that the MCP server is running with those credentials configured as environment variables. In Claude, trigger the authentication flow using the provided auth-spotify commands or UI options to authorize the app with your Spotify account. Once authenticated, Claude will register the MCP toolset and establish a WebSocket session, allowing you to search for music, play tracks, manage playlists, and fetch recommendations directly from Claude.

Common workflows include searching for a track or artist, starting playback, creating a new playlist from discovered tracks, and requesting personalized recommendations based on listening history. The integration aims to provide a seamless bridge between Claude Desktop and Spotify, enabling voice- or text-driven music interactions within Claude.

Prerequisites

• Node.js 16 or higher installed on the host
• npm (or npm-compatible) installed
• Spotify Developer credentials (Client ID and Client Secret)
• Access to a terminal/command prompt

Installation via Smithery (recommended for automatic setup)

1. Install via Smithery with the MCP package:

npx -y @smithery/cli install @imprvhub/mcp-claude-spotify --client claude

2. Start Claude Desktop and ensure the MCP is enabled for Spotify integration.

Manual installation

1. Clone the repository and navigate to the project directory:

git clone https://github.com/imprvhub/mcp-claude-spotify
cd claude-spotify-mcp

2. Install dependencies:

npm install

3. Build the project (if you plan to modify the source):

npm run build

Note: The repository ships with pre-built files in the build directory, so step 3 can be skipped if you don’t modify source.

Configure Spotify credentials

1. Obtain Spotify API credentials from the Spotify Developer Dashboard (Client ID and Client Secret).
2. Set up a Redirect URI of http://127.0.0.1:8888/callback in your Spotify app settings.
3. Place your credentials in the MCP environment when launching:

SPOTIFY_CLIENT_ID=your_client_id_here SPOTIFY_CLIENT_SECRET=your_client_secret_here node build/index.js

Alternatively, configure the environment in your hosting setup per instructions in your environment (e.g., systemd, macOS launch agents, or Windows services).

Environment and configuration tips:

• Ensure the Redirect URI is correctly set in Spotify’s developer dashboard (http://127.0.0.1:8888/callback).
• When integrating with Claude Desktop, you may need to restart Claude after editing the MCP configuration or credentials to properly initialize the tool registry and WebSocket session token cache.
• If you encounter authentication issues, double-check that SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET are correctly exported in the environment where the MCP server runs.
• The path in the mcp_config args should point to the exact built entry file (build/index.js); replace ABSOLUTE_PATH_TO_DIRECTORY with the full path to the repository on your machine.
• For auto-start setups (macOS/Windows/Linux), consider creating appropriate service/launch configurations to ensure the MCP server restarts on reboot or after crashes.