spotify

This MCP server exposes Spotify controls and queries as MCP tools powered by Spotipy. Once running via Docker, you can use commands like search, play, pause, next_track, currently_playing, and numerous library and device related operations (e.g., list_playlists, add_to_liked, transfer_playback, set_volume). The server translates MCP client requests into Spotify API calls, enabling you to control playback, fetch your library, manage queue and playback settings, and query top tracks/artists. To use it, configure your MCP client to launch the Spotify MCP entry as shown in the example config, providing the required environment variables so the container can authenticate with Spotify and persist tokens between runs.

Prerequisites:

• Docker installed on your system
• A Spotify Developer app with Client ID, Client Secret, and Redirect URI set to http://127.0.0.1:8888/callback
• Optional: a path to persist Spotipy tokens (via a Docker volume)

Installation steps:

1. Create a Spotify app and collect Client ID/Secret; ensure Redirect URI matches http://127.0.0.1:8888/callback.
2. Pull or build the MCP image (example uses the prebuilt image): docker pull docker.io/allesy/spotify-mcp:latest
3. Prepare environment variables for OAuth (in your MCP client config): SPOTIPY_CLIENT_ID=your-client-id SPOTIPY_CLIENT_SECRET=your-client-secret SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback SPOTIPY_CACHE_PATH=/app/.cache/token
4. Run the MCP server via Docker (as in the config example or adapt to your MCP client): docker run --rm -i
   -v ${HOME}/.cache/spotify-mcp:/app/.cache
   -e SPOTIPY_CLIENT_ID
   -e SPOTIPY_CLIENT_SECRET
   -e SPOTIPY_REDIRECT_URI
   -e SPOTIPY_CACHE_PATH
   docker.io/allesy/spotify-mcp:latest
5. Perform the OAuth flow following the prompts, which will save a token to the configured cache path. After that, you can restart the MCP client to start issuing Spotify commands without re-authentication.

Tips and considerations:

• The token cache is persisted via a Docker volume or bind mount (SPOTIPY_CACHE_PATH inside the container). Ensure the path matches what you mount on the host to survive container restarts.
• The Redirect URI must exactly match the one configured in your Spotify app.
• If you see issues with ${HOME} expansion in MCP clients, use an absolute host path for the volume mount (e.g., /Users/you/.cache/spotify-mcp:/app/.cache).
• If you need to revoke access, re-run the auth_init flow to refresh tokens.
• When using the MCP client config, remember to map the environment variables in the client’s config so that secrets aren’t hard-coded in the config.
• The server exposes a wide range of tools (Playback & Library, Discovery, Queue, and Device management); refer to the Features section in the README for the full list of available commands.