convez.ai
MCP ServerIntegração & APIsIntermediário
llyfn

Spotify MCP Server

llyfn/spotify-mcp

Controle total do Spotify via Claude com busca, playlists e playback

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-mcp

1 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

Estrelas
5
Forks
4
Acompanhando
0
Saúde
57%
Último commit
há 1 mês
Versão
v0.4.0
Issues abertas
0
Contribuidores
1

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

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, 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, and streamable-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

  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

VariableRequiredDefaultDescription
SPOTIFY_CLIENT_IDYes—Your Spotify app's Client ID
SPOTIFY_CLIENT_SECRETYes—Your Spotify app's Client Secret
SPOTIFY_REDIRECT_URINohttp://127.0.0.1:8888/callbackOAuth redirect URI
SPOTIFY_MCP_TRANSPORTNostdioMCP transport: stdio, sse, or streamable-http

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

Search

ToolDescription
searchSearch for tracks, albums, artists, playlists, shows, episodes, or audiobooks

Albums

ToolDescription
get_albumGet album details by ID
get_albumsBatch lookup — up to 20 album IDs in one call
get_album_tracksGet tracks in an album

Artists

ToolDescription
get_artistGet artist details by ID
get_artistsBatch lookup — up to 50 artist IDs in one call
get_artist_albumsGet albums by an artist

Tracks

ToolDescription
get_trackGet track details by ID
get_tracksBatch lookup — up to 50 track IDs in one call

Playlists

ToolDescription
get_playlistGet playlist details
update_playlistUpdate playlist name, description, or visibility
get_playlist_itemsGet items in a playlist
add_playlist_itemsAdd tracks/episodes to a playlist
remove_playlist_itemsRemove items from a playlist
reorder_playlist_itemsReorder items in a playlist
get_my_playlistsGet the current user's playlists
create_playlistCreate a new playlist

Library

ToolDescription
get_saved_tracksGet saved tracks
get_saved_albumsGet saved albums
get_saved_showsGet saved shows
get_saved_episodesGet saved episodes
get_saved_audiobooksGet saved audiobooks
save_to_librarySave items to library
remove_from_libraryRemove items from library
check_saved_in_libraryCheck if items are in library

Player

ToolDescription
get_playback_stateGet current playback state
get_currently_playingGet the currently playing track
playStart or resume playback
pausePause playback
next_trackSkip to next track
previous_trackSkip to previous track
seekSeek to position in track
set_repeatSet repeat mode (track/context/off)
set_volumeSet playback volume
toggle_shuffleToggle shuffle mode
transfer_playbackTransfer playback to another device
get_devicesGet available devices
add_to_queueAdd item to playback queue
get_queueGet the playback queue
get_recently_playedGet recently played tracks

Shows & Podcasts

ToolDescription
get_showGet show details
get_showsBatch lookup — up to 50 show IDs in one call
get_show_episodesGet episodes of a show
get_episodeGet a single episode by ID
get_episodesBatch lookup — up to 50 episode IDs in one call

Audiobooks

ToolDescription
get_audiobookGet audiobook details
get_audiobooksBatch lookup — up to 50 audiobook IDs in one call
get_audiobook_chaptersGet chapters of an audiobook
get_chapterGet chapter details
get_chaptersBatch lookup — up to 50 chapter IDs in one call

Follow

ToolDescription
get_followed_artistsList artists the user follows (cursor-paginated)
follow_artists_or_usersFollow one or more artists or users by ID
unfollow_artists_or_usersUnfollow one or more artists or users by ID
check_followingCheck whether the user follows given artist/user IDs
follow_playlistFollow a playlist (optionally publicly)
unfollow_playlistUnfollow a playlist

Users

ToolDescription
get_my_profileGet current user's profile
get_my_top_itemsGet top artists or tracks
whoamiDiagnostic — 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.

URIDescription
spotify://me/profileProfile basics — name, country, plan, follower count
spotify://me/playbackCurrent playback state (episode-aware)
spotify://me/queueCurrently playing + next-up queue
spotify://me/top/tracksTop tracks (last ~6 months)
spotify://me/top/artistsTop 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.

PromptDescription
build_playlist_from_recentBuild a new playlist seeded by recent listening (n_tracks)
weekly_listening_summarySummarize the past week's listening grouped by artist/album
playlist_from_artistsBuild a playlist from a comma-separated list of artists (artists, tracks_per_artist)
library_cleanupScan saved tracks and propose cleanup candidates (scan_size)

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT - see LICENSE for details.

Ver o original no GitHub

Bom para

Relacionados