mcp-spotify-player

MCP Spotify Player exposes a Python-based MCP server that lets you control Spotify through natural language commands issued by an AI assistant or MCP client. The server handles OAuth authentication with Spotify, token storage, and a range of playback and discovery capabilities such as play/pause, skip, queue management, volume control, search, browse, and playlist management. You can invoke the server from compatible MCP clients (e.g., Claude Desktop, PyCharm/IntelliJ MCP integrations) by configuring an MCP server entry that points to the mcp_spotify_player module and provides your Spotify credentials via environment variables. The server exposes a web-based OAuth flow for initial authentication and then accepts commands via the MCP interface to translate natural language requests into Spotify API actions.

Prerequisites:

• Python 3.10+ installed on your system
• Git to clone the repository
• A Spotify Developer account to create an app and obtain CLIENT_ID and CLIENT_SECRET

Step-by-step installation:

1. Clone the repository:

git clone <your-repository-url>
cd mcp-spotify-player

2. Install the package in editable mode (for development):

pip install -e .

3. Set up environment variables (example):

cp env.example .env

Edit the .env file with your credentials:

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8000/auth/callback
# Optional: tokens storage path
MCP_SPOTIFY_TOKENS_PATH=/path/to/tokens.json
# Optional: server port for the MCP interface
MCP_SERVER_PORT=3000

4. Run the MCP server:

python -m mcp_spotify_player

Notes:

• The project uses pyproject.toml for dependency management.
• If developing, you can install in editable mode to reflect code changes immediately.

Tips and common issues:

• Ensure SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET, and SPOTIFY_REDIRECT_URI are correctly set and match your Spotify app settings.
• The first run requires completing the OAuth flow in a browser to authorize the application; the server will store access/refresh tokens locally (default path if MCP_SPOTIFY_TOKENS_PATH is not set).
• If your IDE or MCP client cannot reach the server, verify that MCP_SERVER_PORT (default 3000) is open and that the cwd points to your cloned repository.
• You can configure the server in Claude Desktop or similar clients by pointing command to the Python interpreter and passing -m mcp_spotify_player with the appropriate working directory and environment variables.
• Tokens path can be customized; if not set, tokens are stored in ~/.config/mcp_spotify_player/tokens.json by default.