vsaez/mcp-spotify-player

**Control Spotify directly from your AI assistant using the Model Context Protocol**
Installation • Features • API Reference (Python) • Contribute • License
---
Control Spotify from your assistant (Claude/Cursor/Void/IntelliJ).
📖 Table of Contents
- Overview
- Key Features
- Prerequisites
- Installation
- Configuration
- Spotify Configuration
- MCP Configuration with Claude Desktop
- Usage
- API Reference (Python)
- Architecture
- Troubleshooting
- Contribute
- 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**:
2. **Install**:
For development:
3. **Set up environment variables**:
Edit the .env file with your Spotify credentials:
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:
Token file format
When tokens are stored on disk they use a simple JSON structure. Example:
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):
**macOS/Linux** (~/.config/claude/claude_desktop_config.json):
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:
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% |