auxcord-mcp

Spotify MCP Server

A Model Context Protocol (MCP) server that gives AI assistants (Claude Desktop, Cursor, Antigravity, or your own agents) control over Spotify: playback, devices, the queue, search, your library, and playlists.

Highlights

• 32 tools covering playback, devices, the queue, catalog search, your listening history and library, and playlist management, including custom cover art.
• 6 ambient resources (spotify://...) that give the assistant context such as what's playing, your queue and your taste profile, without a tool call.
• Agent-friendly errors. Failures come back as structured JSON with an error_code and recovery guidance (for example, "no active device, call spotify_get_available_devices") instead of raw HTTP errors. Invalid arguments are rejected before reaching Spotify.
• Compact responses. Spotify payloads are trimmed to the fields an assistant actually needs, so they use less of its context window.
• Works locally or over HTTP. It runs over stdio for desktop clients or as a stateless streamable-HTTP server, and handles OAuth 2.0 PKCE login and token refresh for you.

Overview

The server wraps the Spotify Web API as MCP tools and resources. An assistant connected to it can handle requests like "queue three upbeat Daft Punk tracks", "make a playlist from my top tracks this month" or "move playback to my phone".

It signs in as your own Spotify account, using a Spotify developer app you create (see Installation). Playback control requires Spotify Premium.

Tools

Area	Tools
Playback	spotify_play, spotify_pause, spotify_skip_to_next, spotify_skip_to_previous, spotify_seek_to_position, spotify_set_volume, spotify_toggle_shuffle, spotify_set_repeat_mode, spotify_get_playback_state, spotify_get_currently_playing
Devices	spotify_get_available_devices, spotify_transfer_playback
Queue	spotify_get_queue, spotify_add_to_queue
Catalog	spotify_search_catalog, spotify_get_artist, spotify_get_album
User and library	spotify_get_user_profile, spotify_get_top_tracks, spotify_get_top_artists, spotify_get_recently_played, spotify_get_saved_tracks
Playlists	spotify_create_playlist, spotify_get_user_playlists, spotify_get_playlist, spotify_get_playlist_items, spotify_add_tracks_to_playlist, spotify_remove_tracks_from_playlist, spotify_reorder_playlist_tracks, spotify_replace_playlist_tracks, spotify_update_playlist_details, spotify_upload_playlist_cover

Resources: spotify://user/profile, spotify://user/top-tracks, spotify://user/top-artists, spotify://player/current, spotify://player/queue, spotify://playlist/{playlist_id}.

Known Spotify API limitations

These are limits on Spotify's side, not bugs in this server. Each was confirmed against the live Web API or Spotify's changelog.

• Playlist visibility can't be set through the API. Spotify accepts public: false on create and update, but the playlist stays public. For that reason the playlist tools don't offer a public parameter. Set visibility in the Spotify app. (community thread)
• Playlist contents are only available for playlists you own or collaborate on. For other playlists, spotify_get_playlist returns metadata with an explanatory note, and spotify_get_playlist_items returns a PLAYLIST_CONTENTS_UNAVAILABLE error.
• Artist and track metadata is reduced. Spotify no longer returns genres, popularity or followers on artists, popularity on tracks, or label / popularity on albums. Artist top tracks are no longer available, so use spotify_search_catalog with artist:"Name" instead.
• Search returns at most 10 results per type (default 5), and limit + offset can't exceed 1000.
• Playlist search hides some results. Spotify returns some playlist results as null (about 3 in 10 in live testing). spotify_search_catalog drops them and reports how many it dropped in playlists_hidden_by_spotify. If a page comes back mostly or entirely hidden, try the next offset.
• Playlist track counts can lag. Right after tracks are added, spotify_get_user_playlists may report a stale tracks_total. spotify_get_playlist reports the current count.

Usage

After installing, add the server to your MCP client. For Claude Desktop, edit claude_desktop_config.json:

{
  "mcpServers": {
    "spotify": {
      "command": "/path/to/spotify-mcp-server/.venv/bin/python",
      "args": ["/path/to/spotify-mcp-server/main.py"]
    }
  }
}

Restart the client and ask something like "What's playing right now? Add two similar tracks to my queue."

To serve over streamable HTTP instead, for remote or multi-client setups:

python main.py --transport http   # serves http://127.0.0.1:8000/mcp

Then point your client at http://127.0.0.1:8000/mcp. Use --host and --port to change the address.

Installation

You need Python 3.10 or newer and a Spotify account (Premium for playback control).

1. Create a Spotify developer app

1. Open the Spotify Developer Dashboard and click Create app.
2. Add the redirect URI http://127.0.0.1:8888/callback. It must match exactly, including the port and path.
3. Under Which API/SDKs are you planning to use?, select Web API, then save.
4. From the app's Settings, copy the Client ID and Client Secret.

New apps start in Development Mode: your own account works right away, and other accounts must be added under Settings > User Management.

2. Install the server

git clone https://github.com/AtharvBagade/spotify-mcp-server.git
cd spotify-mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

3. Configure credentials

cp .env.example .env

Then fill in .env:

SPOTIFY_CLIENT_ID="your_client_id"
SPOTIFY_CLIENT_SECRET="your_client_secret"
SPOTIFY_REDIRECT_URI="http://127.0.0.1:8888/callback"

# Optional (defaults shown)
SPOTIFY_TOKEN_CACHE_PATH=".spotify_token.json"
MCP_SERVER_NAME="Spotify MCP Server"
MCP_HOST="127.0.0.1"
MCP_PORT=8000
LOG_LEVEL="INFO"

4. Sign in once

python -c "from src.auth import SpotifyAuthManager; from src.config import load_settings; SpotifyAuthManager(load_settings()).get_valid_access_token()"

A browser window opens for you to sign in to Spotify. The token is cached in .spotify_token.json and refreshed automatically after that. If you skip this step, the same sign-in happens on the first tool call. Logs go to stderr; set LOG_LEVEL=DEBUG to include full tracebacks.

Feedback and Contributing

Bug reports and feature requests are welcome in GitHub Issues. Please include the tool name, its arguments and the error_code you got back.

To work on the server, install the development dependencies and run the tests:

pip install -e ".[dev]"
pytest
ruff check src tests