Vuples Spotify

You set up a Model Context Protocol (MCP) server that lets AI assistants search Spotify, view playback information, and control playback across your devices. It exposes a set of tools to find tracks, playlists, and devices, and to play music directly from Spotify through a compatible MCP client.

How to use

You will connect your MCP client to the Vulpes Spotify MCP Server so the assistant can search for tracks, fetch your current playing track, and control playback. Start the server locally, then configure your MCP client to point at the local node process. Once connected, you can use tools to perform actions such as searching for tracks, playing a specific track or playlist, listing devices, and playing through the active Spotify device.

How to install

Prerequisites you need before installation:

• Node.js 16+ (for running the MCP server)
• A Spotify Developer account with a Premium plan for playback control
• An MCP-compatible client (for example Claude Desktop)

Option A — Installing via Smithery (automatic)

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

Manual installation

Follow these steps to install and configure the server manually.

1. Clone the project and install dependencies.

git clone https://github.com/yourusername/spotify-mcp.git
cd spotify-mcp
npm install

2. Create a .env file with your Spotify API credentials.

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
SPOTIFY_REDIRECT_URI=http://localhost:8888

# Optional: For playback control
SPOTIFY_REFRESH_TOKEN=your_refresh_token

3. Generate a refresh token (required for playback control). Choose one of the following methods.

npm run get-token

This starts a local server and provides instructions in the terminal. Alternatively, use the simple script:

node src/simple-auth.js

Open the provided URL in your browser, authorize, copy the redirected URL back to the terminal, and you’ll get a curl command to obtain the refresh token.

Required scopes are already included in the scripts: user-read-playback-state, user-modify-playback-state, user-read-currently-playing, playlist-read-private, playlist-read-collaborative.

4. Add the refresh token to your .env file.

SPOTIFY_REFRESH_TOKEN=your_refresh_token

5. Build the project.

npm run build

Configure MCP client (example for Claude Desktop)

Configure your MCP client to run the Spotify MCP server locally. Create an entry in your Claude Desktop configuration that launches the server with the required environment variables.

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/absolute/path/to/vulpes-spotify-mcp/dist/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://localhost:8888",
        "SPOTIFY_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Troubleshooting

If you encounter issues, check these common problems and fixes.

• No active device found: ensure Spotify is open and playing on at least one device
• Missing permissions: refresh token may lack required scopes
• Not premium: playback control requires a Spotify Premium account
• Refresh token issues: generate a new token and update the .env file and client config

Notes

Important reminders to ensure smooth operation: always have Spotify open on a device before using playback controls, keep the refresh token in sync between your .env file and Claude Desktop config, and restart Claude Desktop after any changes to configuration.

Available tools

spotify-search

Search for tracks by query such as artist, title, or any keyword.

spotify-play

Play a specific track by Spotify ID or URI on your active device.

spotify-currently-playing

Retrieve information about the track currently playing on Spotify.

spotify-devices

List available Spotify playback devices connected to your account.

spotify-search-and-play

Search for a track and automatically play the top result on your active device.

spotify-playlists

List the user's Spotify playlists.

spotify-playlist-tracks

Get tracks from a specific playlist.

spotify-play-playlist

Play a specific playlist, with optional shuffle.

spotify-find-playlist

Find a playlist by name and play it.