Spotify Model Context Protocol (MCP) Server

<p align="center"> <img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg?style=flat-square" alt="Python Version"> <img src="https://img.shields.io/badge/Framework-FastMCP-green.svg?style=flat-square" alt="FastMCP"> <img src="https://img.shields.io/badge/API-Spotify%20Web-1DB954?style=flat-square&logo=spotify" alt="Spotify API"> <img src="https://img.shields.io/badge/MCP-Compatible-orange.svg?style=flat-square" alt="MCP Compatible"> <img src="https://img.shields.io/badge/License-MIT-lightgrey.svg?style=flat-square" alt="License"> </p>

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

1. Go to the Spotify Developer Dashboard and log in.
2. Click Create App.
3. Name your app (e.g., "My MCP Spotify Server") and add a description.
4. In the Redirect URIs field, enter: http://127.0.0.1:8080/callback
5. Check the box for "Web API" under the APIs to request.
6. Click Save.
7. 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:

1. The server can attempt to open a browser to log you in.
2. 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:

1. The agent will call the get_auth_url tool.
2. The agent will display the Spotify login URL to you in the chat.
3. Open the link, log in, authorize, and copy the final URL you redirect to (e.g., http://127.0.0.1:8080/callback?code=...).
4. Paste this URL back to the agent.
5. The agent calls the complete_auth(callback_url) tool.
6. 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.

---

Project created with Gemini Antigravity, with much love. ❤️