convez.ai
MCP ServerIntegração & APIsIntermediário
pete-builds

MCP Spotify — Servidor Remoto para Playlist Control

pete-builds/mcp-spotify

Controle Spotify remoto via MCP, multi-máquina, workaround Feb 2026 API

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP Spotify que roda em Docker como serviço remoto (não subprocess local), expondo 9 ferramentas para criar, gerenciar e editar playlists. Funciona com OAuth persistente e contorna as restrições da API Spotify de Fevereiro de 2026.

Instalação

$npx convez-ai pete-builds/mcp-spotify

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
0
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 2 dias
Versão
v0.1.0
Issues abertas
2
Contribuidores
2

Casos de uso

  • Automação de criação e gerenciamento de playlists via AI
  • Integração Spotify centralizada em homelab ou servidor compartilhado
  • Contorno das limitações de Development Mode da Spotify API 2026

Veredito

Solução pragmática para Spotify MCP em arquiteturas multi-máquina. Documenta bem os quirks recentes da API Spotify (Feb 2026) e oferece fallbacks concretos. Recomendado para quem precisa de controle centralizado de playlists ou experimentação com AI agents.

README

A tradução para o português deste README ainda está na fila.

mcp-spotify

A Spotify MCP server designed to run as a remote service over Streamable HTTP — not a local stdio subprocess.

Most Spotify MCP servers today (varunneal/spotify-mcp, marcelmarais/spotify-mcp-server, etc.) launch as a subprocess on the same machine as your AI client. If you have more than one machine — a homelab, a shared dev server, a laptop that moves around — you end up running N copies with N separate OAuth flows.

This server runs once, in a Docker container, exposes Spotify tools over Streamable HTTP on a port, and any MCP client on your LAN or Tailscale network connects to it with one URL. OAuth happens once in a bootstrap script; the refresh token lives on the server.

Previously published as spotify-mcp-sse. Renamed to mcp-spotify on the migration from the deprecated HTTP+SSE transport to Streamable HTTP (MCP spec 2025-06-18). The old URL https://github.com/pete-builds/spotify-mcp-sse redirects to this repo.

Features

Nine tools, oriented around creating and managing playlists:

ToolPurpose
search_artistResolve artist name → Spotify ID for disambiguation
get_artist_top_tracksArtist's most popular tracks (works around the deprecated /top-tracks endpoint)
create_playlist_from_artistsBuild a new playlist from a list of artist names; shuffle interleaves
add_artists_to_playlistExtend an existing playlist; accepts URL, URI, ID, or exact name
create_playlist_from_tracksBuild a playlist from specific track URIs you already have
list_my_playlistsList playlists you own or follow
update_playlistRename, edit description, toggle public
delete_playlistRemove from your library (Spotify's "unfollow")
remove_tracks_from_playlistRemove specific tracks

Feb 2026 Spotify API migration — why this matters

Spotify shipped a breaking API migration on Feb 11, 2026. If you built a Spotify integration before then and haven't touched it since, it's broken. If you're starting a new one now, Spotify's dashboard quietly puts you in "Development Mode" with severe restrictions. This repo documents and works around all of it:

  • /artists/{id}/top-tracks returns 403 for new apps → falls back to track search with artist: filter
  • Artist search with limit=1 returns the wrong artist (e.g. Radiohead → Thom Yorke) → always requests ≥2 and prefers exact name match
  • Search limit caps at 10 (docs still say 50) → clamps internally
  • POST /users/{id}/playlists removed → uses POST /me/playlists
  • POST /playlists/{id}/tracks → renamed to /items (takes {"uris": [...]})
  • DELETE /playlists/{id}/items takes a different shape: {"items": [{"uri": "..."}]}
  • Write operations require the authenticating user to be explicitly added to the app's User Management tab in the Spotify Developer dashboard (even the app creator)

Quick start

1. Register a Spotify app

https://developer.spotify.com/dashboard → Create app.

  • Redirect URI: http://127.0.0.1:8765/callback (exact — case-sensitive, no trailing slash)
  • API: Web API
  • Save Client ID and Client Secret

In the app's Settings → User Management, add yourself (name + the email on your Spotify account). This is required for any write operations.

2. One-time OAuth bootstrap (on your local machine)

git clone https://github.com/pete-builds/mcp-spotify
cd mcp-spotify
export SPOTIFY_CLIENT_ID=...
export SPOTIFY_CLIENT_SECRET=...
python3 bootstrap.py

Your browser opens, you authorize, the terminal prints a long-lived refresh token.

3. Deploy the server

Copy the code to whatever host will run the container (typically a homelab box, LAN-accessible). Write .env:

SPOTIFY_CLIENT_ID=...
SPOTIFY_CLIENT_SECRET=...
SPOTIFY_REFRESH_TOKEN=...

Start it:

docker compose up -d --build

Server is now at http://<host>:3703/mcp (Streamable HTTP).

4. Register with your MCP client

Claude Code:

claude mcp add spotify http://<host>:3703/mcp --transport http --scope user

Any other MCP client that supports Streamable HTTP: point it at the same URL.

Configuration

Environment variables (all optional except credentials):

VarDefaultPurpose
SPOTIFY_CLIENT_ID—From Spotify Developer dashboard (required)
SPOTIFY_CLIENT_SECRET—From Spotify Developer dashboard (required)
SPOTIFY_REFRESH_TOKEN—From bootstrap.py (required)
MCP_HOST0.0.0.0Bind address
MCP_PORT3703Listening port

The included docker-compose.yml uses network_mode: host. If you'd rather expose with a port mapping, replace that with:

    ports:
      - "3703:3703"

OAuth scopes

Bootstrap requests these:

  • playlist-modify-private
  • playlist-modify-public
  • playlist-read-private

If you add tools that need more (e.g. user-top-read for "my listening history"), extend SCOPES in bootstrap.py and re-run it; you'll get a fresh refresh token with the new permissions.

Architecture

  • FastMCP over Streamable HTTP transport (MCP spec 2025-06-18)
  • httpx async client with in-memory access-token cache and automatic refresh on 401 or expiry
  • Stdlib-only bootstrap helper (http.server, webbrowser, urllib) — no extra deps for the one-time OAuth dance
  • python:3.13-slim base image, fastmcp==3.1.0, httpx==0.28.1

License

MIT. See LICENSE.

Credits

Built by Pete Stergion as part of Brooks New Media's homelab toolkit. The Feb 2026 API workarounds were hard-won; PRs welcome if you spot a cleaner approach.

Ver o original no GitHub

Bom para

Relacionados