Spotify MCP Server
llyfn/spotify-mcp
Controle total do Spotify via Claude com busca, playlists e playback
Ver no GitHubServidor MCP que integra Claude e outros assistentes IA com a Spotify Web API, permitindo buscar músicas, controlar reprodução, gerenciar playlists, biblioteca e podcasts. Cobre praticamente todos os endpoints da API do Spotify com suporte a recursos, prompts pré-configurados e múltiplos transportes.
Instalação
npx convez-ai llyfn/spotify-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Buscar e reproduzir músicas por comando de voz/texto via Claude
- Criar e gerenciar playlists automaticamente com base em preferências
- Controlar playback remoto (play, pause, volume, skip) em diferentes dispositivos
- Explorar biblioteca pessoal, artistas favoritos e podcasts salvos
- Automatizar limpeza de biblioteca e gerenciamento de seguidores
Veredito

Integração madura e completa com a Spotify Web API. Ideal para quem quer automatizar controle de música ou construir assistentes IA interativos. Requer credenciais do Spotify Developer, mas instalação via uvx é simples.
README
A tradução para o português deste README ainda está na fila.
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, chapters — single or batch
- Podcasts & Audiobooks - Browse shows, episodes, audiobooks, and chapters
- Follow - Follow/unfollow artists, users, and playlists
- 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 - Covers all 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 |
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
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
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_albums | Batch lookup — up to 20 album IDs in one call |
get_album_tracks | Get tracks in an album |
Artists
| Tool | Description |
|---|---|
get_artist | Get artist details by ID |
get_artists | Batch lookup — up to 50 artist IDs in one call |
get_artist_albums | Get albums by an artist |
Tracks
| Tool | Description |
|---|---|
get_track | Get track details by ID |
get_tracks | Batch lookup — up to 50 track IDs in one call |
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 |
remove_from_library | Remove items from library |
check_saved_in_library | Check if items are in library |
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_shows | Batch lookup — up to 50 show IDs in one call |
get_show_episodes | Get episodes of a show |
get_episode | Get a single episode by ID |
get_episodes | Batch lookup — up to 50 episode IDs in one call |
Audiobooks
| Tool | Description |
|---|---|
get_audiobook | Get audiobook details |
get_audiobooks | Batch lookup — up to 50 audiobook IDs in one call |
get_audiobook_chapters | Get chapters of an audiobook |
get_chapter | Get chapter details |
get_chapters | Batch lookup — up to 50 chapter IDs in one call |
Follow
| Tool | Description |
|---|---|
get_followed_artists | List artists the user follows (cursor-paginated) |
follow_artists_or_users | Follow one or more artists or users by ID |
unfollow_artists_or_users | Unfollow one or more artists or users by ID |
check_following | Check whether the user follows given artist/user IDs |
follow_playlist | Follow a playlist (optionally publicly) |
unfollow_playlist | Unfollow a playlist |
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 — name, country, plan, follower count |
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.