MCP 服务器

Spotify MCP Server

A robust MCP server that connects Spotify playback, search, and library management to LLM agents via tools, with dual authentication and reliable token handling.

README

Spotify Model Context Protocol (MCP) Server

A robust, production-grade Model Context Protocol (MCP) server that connects Spotify playback, search, and library management directly to LLM Agents (such as Cursor, Claude Desktop, and other MCP clients).

Built in Python using FastMCP and Spotipy, this server includes connection pooling, log isolation, and a custom dual-authentication strategy to ensure long-term stability and compatibility with non-interactive agents.

Features

Playback Control: Play tracks/albums/playlists, pause, skip, adjust volume, toggle shuffle/repeat, and transfer playback between devices.
Search & Discovery: Search tracks, artists, albums, and playlists, and get tailored music recommendations based on genres/artists.
Library Management: View and modify your "Liked Songs" library and create/manage playlists.
Dual Authentication: Local web redirect or manual copy-paste fallback designed to run seamlessly through the agent interface.
Robust Connection Handling: Connection pooling via requests.Session and thread-safe automatic token refreshing to prevent memory leaks and credentials expiration crashes.
Log Safety: All server logs and debug outputs are isolated to stderr, leaving stdout purely for MCP protocol messages.

Setup & Configuration

Prerequisites

Python 3.10+
A Spotify account (Spotify Premium is required for playback control features).

1. Register Spotify App

Go to the Spotify Developer Dashboard and log in.
Click Create App.
Name your app (e.g., "My MCP Spotify Server") and add a description.
In the Redirect URIs field, enter: http://127.0.0.1:8080/callback
Check the box for "Web API" under the APIs to request.
Click Save.
In the settings page of your new app, retrieve the Client ID and Client Secret.

2. Configure Environment Variables

Create a file named .env in the root of the Spotify MCP folder:

SPOTIPY_CLIENT_ID=your_spotify_client_id
SPOTIPY_CLIENT_SECRET=your_spotify_client_secret
SPOTIPY_REDIRECT_URI=http://127.0.0.1:8080/callback

Installation & Running

Ensure you have created the virtual environment and installed dependencies:

cd "Spotify MCP"
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run Server Locally

To run and inspect the server using the MCP CLI tool:

# Activate virtual environment
source .venv/bin/activate

# Start the dev inspector
mcp dev src/server.py

Client Integration

Add the server to your MCP client configuration (e.g., Cursor, Claude Desktop, or custom MCP client).

For example, in claude_desktop_config.json:

{
  "mcpServers": {
    "spotify": {
      "command": "/root/Spotify MCP/.venv/bin/python",
      "args": [
        "-m",
        "src.server"
      ],
      "env": {
        "SPOTIPY_CLIENT_ID": "your_spotify_client_id",
        "SPOTIPY_CLIENT_SECRET": "your_spotify_client_secret",
        "SPOTIPY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
      }
    }
  }
}

Authentication Flow

Because MCP servers run in background processes without terminal input, the server supports a smooth dual-authentication flow:

Flow 1: Automated Local Redirect (Default)

When starting up, if credentials are set but not authorized:

The server can attempt to open a browser to log you in.
Once authorized, the Spotify callback redirects to http://127.0.0.1:8080/callback?code=... which is processed, and tokens are written to .spotify_token_cache in the project root.

Flow 2: Interactive LLM/Agent Authorization (Recommended fallback)

If Flow 1 is blocked or you are running the agent on a remote environment:

The agent will call the get_auth_url tool.
The agent will display the Spotify login URL to you in the chat.
Open the link, log in, authorize, and copy the final URL you redirect to (e.g., http://127.0.0.1:8080/callback?code=...).
Paste this URL back to the agent.
The agent calls the complete_auth(callback_url) tool.
The server finishes the auth flow, caches the tokens, and immediately gains access!

Available Tools

The server exposes 25 tools categorized as follows:

Category	Tool	Description
System	`is_authenticated`	Verifies connection status and logged-in user profile.
	`get_auth_url`	Generates the login URL to authorize Spotify.
	`complete_auth`	Validates callback redirect and stores tokens.
Playback	`get_current_playback`	Shows what's playing, active device, progress bar, volume, etc.
	`play_track`	Plays a track by name search or exact URI.
	`play_context`	Plays an album, playlist, or artist by URI.
	`pause_playback`	Pauses Spotify.
	`next_track`	Skips to the next song in the queue.
	`previous_track`	Plays the previous song in history.
	`set_volume`	Sets volume level (0 to 100).
	`get_available_devices`	Lists connected Spotify clients with their status and IDs.
	`transfer_playback`	Switches active playback to another device ID.
	`toggle_shuffle`	Toggles shuffle state.
	`set_repeat_mode`	Sets repeat mode ('track', 'context', 'off').
Search	`search_spotify`	Searches for tracks, albums, artists, or playlists.
	`get_recommendations`	Recommends tracks based on seed genres, artists, or tracks.
	`get_featured_playlists`	Retrieves current Spotify editorial featured playlists.
	`get_lyrics`	Retrieves song lyrics from Genius.com via web scraping.
Library	`get_user_playlists`	Lists playlists in the user's library.
	`create_playlist`	Creates a new playlist.
	`add_to_playlist`	Adds tracks (comma-separated URIs) to a playlist.
	`get_playlist_tracks`	Lists tracks in a specific playlist.
	`get_user_saved_tracks`	Lists Liked Songs.
	`save_tracks`	Adds tracks to Liked Songs.
	`remove_tracks`	Removes tracks from Liked Songs.