Mcp Spotify Player

🎵 MCP Spotify Player

[](https://github.com/vsaez/mcp-spotify-player/actions)

[](https://github.com/vsaez/mcp-spotify-player/releases) [](https://github.com/vsaez/mcp-spotify-player/commits/main) [](https://github.com/vsaez/mcp-spotify-player/stargazers) [](https://github.com/vsaez/mcp-spotify-player/blob/main/LICENSE) [](https://github.com/vsaez/mcp-spotify-player/issues) [](https://github.com/vsaez/mcp-spotify-player/pulls)

Control Spotify directly from your AI assistant using the Model Context Protocol

[Installation](#installation) • [Features](#key-features) • [API Reference (Python)](#api-reference-python) • [Contribute](#contribute) • [License](#license)

---

Control Spotify from your assistant (Claude/Cursor/Void/IntelliJ).

📖 Table of Contents

• [Overview](#overview)
• [Key Features](#key-features)
• [Prerequisites](#prerequisites)
• [Installation](#installation)
• [Configuration](#configuration)
• [Spotify Configuration](#spotify-configuration)
• [MCP Configuration with Claude Desktop](#mcp-configuration-with-claude-desktop)
• [Usage](#usage)
• [API Reference (Python)](#api-reference-python)
• [Architecture](#architecture)
• [Troubleshooting](#troubleshooting)
• [Contribute](#contribute)
• [License](#license)

🎯 Overview

MCP Spotify Player is an innovative tool that integrates Spotify control with AI assistants via the Model Context Protocol (MCP). It enables users to control their music using natural language commands processed by an AI assistant, delivering a seamless music interaction experience.

Why MCP Spotify Player?

• AI Integration: Full Spotify control via natural language
• Automatic Authentication: Secure and simplified OAuth flow
• High Performance: Fast responses to commands
• Extensible: Modular architecture for adding features
• Open Source: Active community and transparent development

✨ Key Features

🎵 Playback Control

• ▶️ Play / Pause music
• ⏭️ Skip tracks
• 🔄 Queue management
• 🔊 Volume control
• 🔁 Repeat modes

🔍 Search & Discovery

• Search tracks, artists and albums
• Browse playlists
• Personalized recommendations
• Playback history

📱 Device Management

• Switch between available devices
• Multi-device synchronization
• Remote playback control

🎨 Playlist Management

• Create and edit playlists
• Add / remove tracks
• Automatic organization
• Share playlists

📋 Prerequisites

Before you begin, make sure you have installed:

• Python 3.10+
• Spotify premium account - Premium recommended
• Spotify App - Create an app

🔧 Installation

1. Clone the repository:

   git clone 
   cd mcp-spotify-player

1. Install:

  pip install .

For development:

  pip install -e .

1. Set up environment variables:

cp env.example .env

Edit the .env file with your Spotify credentials:

   SPOTIFY_CLIENT_ID=your_client_id_here
   SPOTIFY_CLIENT_SECRET=your_client_secret_here
   SPOTIFY_REDIRECT_URI=http://127.0.0.1:8000/auth/callback
   # Optional: custom path to store OAuth tokens
   # Defaults to ~/.config/mcp_spotify_player/tokens.json
   MCP_SPOTIFY_TOKENS_PATH=/path/to/tokens.json

Note: dependencies are managed with pyproject.toml.

If MCP_SPOTIFY_TOKENS_PATH is not set, tokens will be stored in ~/.config/mcp_spotify_player/tokens.json by default.

⚙️ Configuration

Spotify Configuration

Create an application on the Spotify Developer Dashboard

1. Go to Spotify Developer Dashboard
2. Create a new application
3. Get your CLIENT_ID and CLIENT_SECRET
4. In the app settings, add http://127.0.0.1:8000/auth/callback as a redirect URI

Configure credentials

Create a .env file at the project root: ``env SPOTIFY_CLIENT_ID=your_client_id_here SPOTIFY_CLIENT_SECRET=your_client_secret_here SPOTIFY_REDIRECT_URI=http://localhost:3000/callback MCP_SERVER_PORT=3000 ``

Token file format

When tokens are stored on disk they use a simple JSON structure. Example:

{
  "access_token": "ACCESS",
  "refresh_token": "REFRESH",
  "expires_at": 1700000000,
  "scopes": [
    "user-read-playback-state",
    "user-modify-playback-state",
    "user-read-currently-playing",
    "user-read-recently-played",
    "user-read-playback-position",
    "user-top-read",
    "playlist-read-private",
    "playlist-read-collaborative",
    "playlist-modify-private",
    "user-library-read",
    "user-library-modify"
  ]
}

By default tokens are saved to ~/.config/mcp_spotify_player/tokens.json unless MCP_SPOTIFY_TOKENS_PATH is configured.

MCP Configuration with Claude Desktop

Add the server to your Claude Desktop configuration or other MCP client:

Windows (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "spotify-player": {
      "command": "C:/path/to/python/distribution/python.exe",
      "args": [
        "-m",
        "mcp_spotify_player"
      ],
      "cwd": "C:/path/to/cloned/repo/mcp-spotify-player",
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8000/auth/callback"
      }
    }
  }
}

macOS/Linux (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "spotify-player": {
      "command": "/path/to/python/distribution/python.exe",
      "args": [
        "-m",
        "mcp_spotify_player"
      ],
      "cwd": "/path/to/cloned/repo/mcp-spotify-player",
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8000/auth/callback"
      }
    }
  }
}

Configuring MCP Server in PyCharm / IntelliJ

JetBrains IDEs (PyCharm, IntelliJ, etc.) with GitHub Copilot have native support for MCP servers.

1. Go to File → Settings → GitHub Copilot → Model Context Protocol (MCP).
2. On the right side, click Configure to edit the mcp.json file.
3. Add the following snippet, replacing the paths and dummy credentials as needed:

{
  "servers": {
    "spotify-player": {
      "command": "C:/Users/YourUser/AppData/Local/Programs/Python/Python311/python.exe",
      "args": ["-m", "mcp_spotify_player"],
      "cwd": "/path/to/cloned/repo/mcp-spotify-player",
      "env": {
        "SPOTIFY_CLIENT_ID": "your-client-id",
        "SPOTIFY_CLIENT_SECRET": "your-client-secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8000/auth/callback"
      }
    }
  }
}

Replace your-client-id and your-client-secret with the credentials from your Spotify Developer Dashboard. Do not commit your real credentials into version control.

Once configured, the server will appear in the Copilot Agent inside PyCharm/IntelliJ, and tools like /auth, /play_music, and /pause_music can be invoked directly.

Other MCP clients

Use mcp-spotify-player.yaml as a template (same fields: command, args, cwd, env).

🎮 Usage

Available Commands

| Command | Description | Example | |---------|-------------|---------| | play_music | Play music | play_music — Play Where Is My Mind by The Pixies | | pause_music | Pause playback | pause_music — Pause the music | | skip_next | Next track | skip_next — Next song | | skip_previous | Previous track | skip_previous — Previous song | | set_volume | Set playback volume (0-100) | set_volume — Set volume to 50% | | set_repeat | Set repeat mode (off, track, context) | set_repeat — Set repeat mode to off, track, or context (e.g., "Repeat current track") | | get_current_playing | Get the currently playing track | get_current_playing — What's playing? | | get_playback_state | Get full playback state | get_playback_state — What's the playback state? | | get_devices | List available playback devices | get_devices — List my available devices | | search_music | Search for tracks/artists/albums | search_music — Search for songs by Queen | | search_collections | Search for playlists or albums | search_collections — Search for playlists or albums | | get_playlists | List user playlists | get_playlists — List my playlists | | get_playlist_tracks | Get tracks in a playlist | get_playlist_tracks — Show tracks in playlist 'Road Trip' | | get_artist | Get artist information by ID | get_artist — Show info about artist with a given ID | | get_artist_albums | Get albums for an artist by ID | get_artist_albums — Show albums of an artist by ID | | get_artist_top_tracks | Get top tracks for an artist by ID | get_artist_top_tracks — Show top tracks of an artist by ID | | get_album | Get album information by ID | get_album — Show info about album 'The Dark Side of the Moon' | | get_albums | Get multiple albums information | get_albums — Show info about multiple albums | | get_album_tracks | Get tracks in an album | get_album_tracks — Show tracks in album 'The Dark Side of the Moon' | | get_saved_albums | List saved albums in library | get_saved_albums — List my saved albums | | check_saved_albums | Check if albums are saved | check_saved_albums — Check if these albums are saved | | save_albums | Save albums to library | save_albums — Save these albums to my library | | delete_saved_albums | Remove albums from library | delete_saved_albums — Remove these albums from my library | | create_playlist | Create a new playlist | create_playlist — Create playlist 'Road Trip' with these songs...' | | rename_playlist | Rename an existing playlist | rename_playlist — Rename playlist 'Road Trip' to 'Vacation' | | clear_playlist | Remove all tracks from a playlist | clear_playlist — Remove all songs from playlist 'Road Trip' | | add_tracks_to_playlist | Add tracks to a playlist | add_tracks_to_playlist — Add these songs to playlist 'Road Trip' | | queue_add | Add a track to the queue | queue_add — Add this track to the queue | | queue_list | Show upcoming queue | queue_list — Show the upcoming queue | | diagnose | Display diagnostic information | diagnose — Display diagnostic information |

Usage Examples

With Claude or your AI assistant:

User: "Play relaxing music for work"
Claude: [Performs search and plays a relaxing playlist]

User: "Raise the volume to 80%"
Claude: [Sets volume to 80%]

User: "Create a playlist with the best 80s songs"
Claude: [Creates playlist and adds popular 80s tracks]

Programmatic usage (Python)

from pathlib import Path
from mcp_spotify_player.spotify_controller import SpotifyController
from mcp_spotify_player.client_auth import load_tokens

# Load tokens from the default path (adjust if you store them elsewhere)
tokens_path = Path.home() / '.config' / 'mcp_spotify_player' / 'tokens.json'
# load_tokens returns a Tokens object or raises if missing
tokens = load_tokens(tokens_path)

# SpotifyController expects a zero-arg callable that returns tokens
controller = SpotifyController(lambda: tokens)

if not controller.is_authenticated():
    raise SystemExit("Run the auth tool first (use the auth command in your MCP client)")

# Play a song by query (search + play)
controller.play_music(query="Bohemian Rhapsody")

# Get currently playing track
current = controller.get_current_playing()
if current and current.get("item"):
    name = current["item"]["name"]
    artist = current["item"]["artists"][0]["name"]
    print(f"Now playing: {name} — {artist}")

# Create a playlist and add tracks (example)
playlist_resp = controller.create_playlist(playlist_name="Road Trip 2024", description="Road trip mix")
# create_playlist returns {"success": True, "playlist": {...}}
playlist_id = None
if isinstance(playlist_resp, dict) and playlist_resp.get("success") and playlist_resp.get("playlist"):
    playlist_id = playlist_resp["playlist"].get("id")

if playlist_id:
    controller.add_tracks_to_playlist(playlist_id=playlist_id, track_uris=["spotify:track:TRACK_URI_1", "spotify:track:TRACK_URI_2"])
else:
    print("Could not create playlist or retrieve playlist id")

📚 API Reference (Python)

This project exposes a Python-first API via the SpotifyController facade. The controller delegates functionality to PlaybackController, PlaylistController, Albums and Artists controllers. Signatures and return values below reflect the current implementation.

SpotifyController

A facade that aggregates playback, playlist, album and artist operations.

Constructor

SpotifyController(tokens_provider: Callable[[], Optional[Tokens]])

• tokens_provider: zero-argument callable that returns a Tokens object or None.

Methods (delegated to underlying controllers)

• is_authenticated() -> bool
• Returns True if tokens are present and not expired.

Playback-related (via PlaybackController)

• playmusic(query: Optional[str] = None, playlistname: Optional[str] = None, trackuri: Optional[str] = None, artisturi: Optional[str] = None) -> Dict[str, Any]
• Play a track by search query, specific track URI, playlist name or artist URI. Returns a dict with success/message and optional details.

• pause_music() -> Dict[str, Any]
• Pause playback.

• skip_next() -> Dict[str, Any]
• Skip to next track.

• skip_previous() -> Dict[str, Any]
• Skip to previous track.

• setvolume(volumepercent: int) -> Dict[str, Any]
• Set device volume (0-100).

• set_repeat(state: str) -> Dict[str, Any]
• Set repeat mode. state is one of 'off', 'track', 'context'.

• getcurrentplaying() -> Dict[str, Any]
• Returns a dict with success and track info (name, artist, album, uri, durationms, externalurl), isplaying and progressms.

• getplaybackstate() -> Dict[str, Any]
• Returns full playback state including isplaying, currenttrack (TrackInfo dict) volumepercent, devicename, shufflestate and repeatstate.

• get_devices() -> Dict[str, Any]
• Returns a list of available playback devices.

• searchmusic(query: str, searchtype: str = "track", limit: int = 10) -> Dict[str, Any]
• Search for tracks or artists. For track searches returns a list of TrackInfo dicts.

• search_collections(q: str, type: str, limit: int = 20, offset: int = 0, market: Optional[str] = None) -> Dict[str, Any]
• Search for playlists or albums. Returns container info and items.

• queueadd(uri: str, deviceid: Optional[str] = None) -> Dict[str, Any]
• Add a track/episode URI to the active device queue.

• queue_list(limit: Optional[int] = None) -> Dict[str, Any]
• Get the upcoming queue (delegates to the client).

PlaylistController

• get_playlists() -> Dict[str, Any]
• Returns user's playlists as a list of PlaylistInfo dicts.

• createplaylist(playlistname: str, description: str = "") -> Dict[str, Any]
• Create a new playlist (private by default). Returns the created playlist info.

• getplaylisttracks(playlist_id: str, limit: int = 20) -> Dict[str, Any]
• Return tracks in a playlist as TrackInfo dicts.

• renameplaylist(playlistid: str, playlist_name: str) -> Dict[str, Any]
• Rename a playlist.

• clearplaylist(playlistid: str) -> Dict[str, Any]
• Remove all tracks from a playlist.

• addtrackstoplaylist(playlistid: str, track_uris: List[str]) -> Dict[str, Any]
• Add valid Spotify track URIs (spotify:track:...) to a playlist.

Data models returned (summary)

• TrackInfo: dict with keys: name, artist, album, uri, durationms, externalurl
• PlaylistInfo: dict with playlist metadata (id, name, description, owner, track_count, uri)

Example (Python)

from pathlib import Path
from mcp_spotify_player.client_auth import load_tokens
from mcp_spotify_player.spotify_controller import SpotifyController

tokens = load_tokens(Path.home() / '.config' /

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vsaez](https://github.com/vsaez)
- **Source:** [vsaez/mcp-spotify-player](https://github.com/vsaez/mcp-spotify-player)
- **License:** MIT

Install and usage instructions live in the source repository linked above.