Skip to main content

Spotify MCP Server

PyPI

A Model Context Protocol (MCP) server that provides tools for interacting with the Spotify Web API. Enables AI assistants like Claude to search music, control playback, manage playlists, and more.

Features

  • Search - Find tracks, albums, artists, playlists, shows, episodes, and audiobooks
  • Playback Control - Play, pause, skip, seek, volume, shuffle, repeat, queue management
  • Playlists - Create, update, add/remove/reorder tracks (auto-chunks large batches)
  • Library - View and manage saved tracks, albums, shows, episodes, and audiobooks
  • Browse - Get details on tracks, albums, artists, episodes, and chapters
  • Podcasts & Audiobooks - Browse shows, episodes, audiobooks, and chapters
  • Follow - List followed artists; follow/unfollow artists, users, and playlists through the library tools by URI
  • User Profile - View profile, top artists/tracks, diagnostic whoami
  • Resources - Subscribable snapshots of profile, playback, queue, top items
  • Prompts - Pre-baked workflows for playlist building, listening summaries, library cleanup
  • Transports - stdio (default), sse, and streamable-http
  • Uses only non-deprecated Spotify Web API endpoints

Example interactions

  • "What am I listening to right now?"
  • "Play some Radiohead on my living room speaker."
  • "Skip this track and turn the volume down to 30."
  • "Build me a playlist of 25 chill tracks based on what I've been listening to this week."
  • "Add the last three songs I played to my 'Focus' playlist."
  • "Show me my top artists from the last six months."
  • "Search for live albums by Nils Frahm and save the best one to my library."
  • "Unfollow every playlist I haven't opened that wasn't made by me."
  • "Queue up the next episode of the show I was listening to yesterday."

Prerequisites

  • uv — install with curl -LsSf https://astral.sh/uv/install.sh | sh
  • A Spotify Developer account
  • A Spotify app with Client ID and Client Secret

Getting Your Spotify Credentials

  1. Go to the Spotify Developer Dashboard
  2. Click Create App
  3. Fill in the app details:
    • App name: Choose any name (e.g., "My MCP Server")
    • App description: Optional
    • Redirect URI: http://127.0.0.1:8888/callback
    • Which API/SDKs are you planning to use?: Select Web API
  4. Click Save
  5. On your app's page, find your Client ID
  6. Click Show client secret to reveal your Client Secret

Important: The redirect URI must exactly match http://127.0.0.1:8888/callback (or whatever you set in SPOTIFY_REDIRECT_URI). Do not use localhost — use 127.0.0.1.

Installation

Pick your client below. All examples use uvx to fetch the server on demand — no clone, no manual install.

Claude Code

claude mcp add spotify \
  -e SPOTIFY_CLIENT_ID=your_client_id \
  -e SPOTIFY_CLIENT_SECRET=your_client_secret \
  -- uvx mcp-server-spotify

Other MCP clients

Most MCP clients configure servers via a JSON file. Add this entry to your client's MCP config:

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["mcp-server-spotify"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Running from a local checkout

For development, or if you want to run a modified copy:

git clone https://github.com/llyfn/spotify-mcp.git
cd spotify-mcp && uv sync

Then point your client at the local checkout instead of uvx:

"command": "uv",
"args": ["--directory", "/absolute/path/to/spotify-mcp", "run", "mcp-server-spotify"]

Configuration

Variable Required Default Description
SPOTIFY_CLIENT_ID Yes — Your Spotify app's Client ID
SPOTIFY_CLIENT_SECRET Yes — Your Spotify app's Client Secret
SPOTIFY_REDIRECT_URI No http://127.0.0.1:8888/callback OAuth redirect URI
SPOTIFY_MCP_TRANSPORT No stdio MCP transport: stdio, sse, or streamable-http

Spotify API notes

Development-mode Spotify apps have these restrictions (see the February 2026 migration guide):

  • The app owner needs an active Spotify Premium subscription.
  • API quota is shared by all Client IDs on the developer account. When it runs out, tools report Quota exceeded.
  • Search returns at most 10 results per type.
  • Full playlist contents are only returned for playlists you own or collaborate on.

Authentication

The server uses Spotify's Authorization Code flow:

  1. On first use, the server opens your browser to Spotify's login page
  2. Spotify will ask you to approve access — the server requests all scopes needed for the full tool set (playback, library, playlists, and user data)
  3. After you authorize, Spotify redirects to the local callback server
  4. The server exchanges the authorization code for access/refresh tokens
  5. Tokens are stored securely in ~/.spotify-mcp/credentials.json
  6. Tokens are automatically refreshed when they expire

If running in a headless environment (SSH, Docker), the auth URL will be printed to stderr — copy and paste it into a browser manually.

Re-authenticating

To re-authenticate (e.g., after revoking access), delete the stored credentials:

rm ~/.spotify-mcp/credentials.json

Available Tools

Tool Description
search Search for tracks, albums, artists, playlists, shows, episodes, or audiobooks

Albums

Tool Description
get_album Get album details by ID
get_album_tracks Get tracks in an album

Artists

Tool Description
get_artist Get artist details by ID
get_artist_albums Get albums by an artist

Tracks

Tool Description
get_track Get track details by ID

Playlists

Tool Description
get_playlist Get playlist details
update_playlist Update playlist name, description, or visibility
get_playlist_items Get items in a playlist
add_playlist_items Add tracks/episodes to a playlist
remove_playlist_items Remove items from a playlist
reorder_playlist_items Reorder items in a playlist
get_my_playlists Get the current user's playlists
create_playlist Create a new playlist

Library

Tool Description
get_saved_tracks Get saved tracks
get_saved_albums Get saved albums
get_saved_shows Get saved shows
get_saved_episodes Get saved episodes
get_saved_audiobooks Get saved audiobooks
save_to_library Save items to library, or follow artists/users/playlists by URI (max 40/request, auto-chunked)
remove_from_library Remove items from library, or unfollow artists/users/playlists by URI (max 40/request, auto-chunked)
check_saved_in_library Check if items are saved, or artists/users/playlists are followed, by URI (max 40/request, auto-chunked)

Player

Tool Description
get_playback_state Get current playback state
get_currently_playing Get the currently playing track
play Start or resume playback
pause Pause playback
next_track Skip to next track
previous_track Skip to previous track
seek Seek to position in track
set_repeat Set repeat mode (track/context/off)
set_volume Set playback volume
toggle_shuffle Toggle shuffle mode
transfer_playback Transfer playback to another device
get_devices Get available devices
add_to_queue Add item to playback queue
get_queue Get the playback queue
get_recently_played Get recently played tracks

Shows & Podcasts

Tool Description
get_show Get show details
get_show_episodes Get episodes of a show
get_episode Get a single episode by ID

Audiobooks

Tool Description
get_audiobook Get audiobook details
get_audiobook_chapters Get chapters of an audiobook
get_chapter Get chapter details

Follow

Tool Description
get_followed_artists List artists the user follows (cursor-paginated)

Users

Tool Description
get_my_profile Get current user's profile
get_my_top_items Get top artists or tracks
whoami Diagnostic — auth status, active device, configured scopes

Resources

Snapshots of user state exposed under the spotify:// URI scheme. MCP clients can include them as context or subscribe for updates without calling a tool.

URI Description
spotify://me/profile Profile basics — display name, user ID, account ID
spotify://me/playback Current playback state (episode-aware)
spotify://me/queue Currently playing + next-up queue
spotify://me/top/tracks Top tracks (last ~6 months)
spotify://me/top/artists Top artists (last ~6 months)

Prompts

Canned workflows MCP clients can offer in their prompt picker. Each one walks the assistant through a multi-step task using the tools above.

Prompt Description
build_playlist_from_recent Build a new playlist seeded by recent listening (n_tracks)
weekly_listening_summary Summarize the past week's listening grouped by artist/album
playlist_from_artists Build a playlist from a comma-separated list of artists (artists, tracks_per_artist)
library_cleanup Scan saved tracks and propose cleanup candidates (scan_size)

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT - see LICENSE for details.

Metadata

Release files for mcp-server-spotify 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-server-spotify 0.3.1
File Size Uploaded Provenance Actions
mcp_server_spotify-0.3.1.tar.gz 84.2 kB With provenance Details for mcp_server_spotify-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-server-spotify 0.3.1
File Interpreter ABI Platform Actions
mcp_server_spotify-0.3.1-py3-none-any.whl Python 3 none any Details for mcp_server_spotify-0.3.1-py3-none-any.whl

Total release size: 118.5 kB

Release files / mcp_server_spotify-0.3.1.tar.gz

Download URL mcp_server_spotify-0.3.1.tar.gz
Size 84.2 kB
Tags Source
SHA-256 checksum
How to use checksums
e62aae4835331b03b9e27d83e603c53c6935ad0e70d9d2eb23b6461a2b907984
BLAKE2b-256 checksum
How to use checksums
0f82980fde38a2b3c47094fe3927c057b6f715aca55b156d6d9ed04b00599cd2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

Release files / mcp_server_spotify-0.3.1-py3-none-any.whl

Download URL mcp_server_spotify-0.3.1-py3-none-any.whl
Size 34.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
00a0f60d3e102d8ecb4022f84e80b7a58c22e6a8ec4f812f9413c32ac1a95a09
BLAKE2b-256 checksum
How to use checksums
c90eefacd01aa05797e74e8286854a74f09845f0f98264f41796aa4a17b8bf2d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

Security for mcp-server-spotify 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mcp_server_spotify-0.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page