Spotify MCP Server
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, andstreamable-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
- Go to the Spotify Developer Dashboard
- Click Create App
- 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
- Click Save
- On your app's page, find your Client ID
- 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 inSPOTIFY_REDIRECT_URI). Do not uselocalhost— use127.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_MCP_AUTH_TOKEN |
For sse/streamable-http |
— | Bearer token clients must send on every request (min. 32 ASCII chars) |
SPOTIFY_MCP_HOST |
No | 127.0.0.1 |
HTTP bind address. Non-loopback values require SPOTIFY_MCP_ALLOWED_HOSTS |
SPOTIFY_MCP_PORT |
No | 8000 |
HTTP port |
SPOTIFY_MCP_ALLOWED_HOSTS |
No | — | Comma-separated Host header values to accept, e.g. spotify.example.com or 10.0.0.5:* |
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:
- On first use, the server opens your browser to Spotify's login page
- Spotify will ask you to approve access — the server requests all scopes needed for the full tool set (playback, library, playlists, and user data)
- After you authorize, Spotify redirects to the local callback server
- The server exchanges the authorization code for access/refresh tokens
- Tokens are stored securely in
~/.spotify-mcp/credentials.json - Tokens are automatically refreshed when they expire
In stdio mode, if running in a headless environment (SSH, Docker), the auth URL will be printed to stderr — copy and paste it into a browser manually.
Remote servers
HTTP transports never start the browser login themselves. Authorize once on the server host:
ssh -L 8888:127.0.0.1:8888 you@server # forwards Spotify's callback to the server
mcp-server-spotify auth # run on the server, in that SSH session, with your SPOTIFY_* env vars
uvx users run uvx mcp-server-spotify auth. Open the printed URL in your local browser; the 8888 must match the port in SPOTIFY_REDIRECT_URI. Run auth as the user the server runs as, since credentials are written to that user's ~/.spotify-mcp. Alternatively, run mcp-server-spotify auth on any machine and copy ~/.spotify-mcp/credentials.json to the server (for containers, into a volume mounted at the user's ~/.spotify-mcp); this works only with the same SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET on both.
Re-authenticating
To re-authenticate (e.g., after revoking access), delete the stored credentials:
rm ~/.spotify-mcp/credentials.json
Available Tools
Search
| 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.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_server_spotify-0.4.0.tar.gz | 91.2 kB | With provenance | Details for mcp_server_spotify-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_server_spotify-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for mcp_server_spotify-0.4.0-py3-none-any.whl |
Total release size: 128.9 kB
Release files / mcp_server_spotify-0.4.0.tar.gz
| Download URL | mcp_server_spotify-0.4.0.tar.gz |
|---|---|
| Size | 91.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c00a2a06d7ebe9b2e8f1291f39b58a212d239e0c589addd374fb3d9b3a393348
|
|
BLAKE2b-256 checksum How to use checksums |
e7a32e6acc1df28ce186b136d2fd4474204d7a0c300424cdccacdd7c144e5f47
|
| 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 logRelease files / mcp_server_spotify-0.4.0-py3-none-any.whl
| Download URL | mcp_server_spotify-0.4.0-py3-none-any.whl |
|---|---|
| Size | 37.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
68911586aae6d1168a04ff331b7dc2f2685d9ee3013b4384ed5c57b2d54ce898
|
|
BLAKE2b-256 checksum How to use checksums |
0cce4161d7084de968385b2b42d49414243d8efafe0e71ae25d35beb6cff5e92
|
| 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 logSecurity for mcp-server-spotify 0.4.0
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.
Attestation for mcp_server_spotify-0.4.0.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 logA 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.