spotify-mcp

Un servidor MCP que envuelve spotipy para que Claude (o cualquier cliente MCP) pueda buscar en Spotify y leer listas de reproducción, canciones guardadas, catálogos de artistas y señales de descubrimiento.

Construido específicamente como el backend de Spotify de re-com — orientado a la lectura por diseño, no un servidor de control de reproducción. Sí admite crear listas de reproducción y añadirles canciones (para que una lista de recomendaciones de re-com pueda convertirse en una lista real), pero no hay control de reproducción/pausa/cola; para eso, mira uno de los varios servidores MCP de Spotify centrados en la reproducción que ya existen.

Herramientas

Una limitación real, dicha claramente: Spotify restringe /recommendations y artist_related_artists para aplicaciones API creadas después de noviembre de 2024 que no tengan "Extended Quota Mode" (una aprobación manual que Spotify otorga con moderación). Si tu aplicación no lo tiene, get_recommendations y get_related_artists devolverán 403 — handle_errors lo convierte en un mensaje claro en lugar de un traceback crudo, y spotify_client.py de re-com lo trata como una señal no disponible, no como un error fatal. search_music, las listas de reproducción, las canciones guardadas y los mejores temas de artistas no se ven afectados.

Otros proyectos de Claude Code en esta máquina (p. ej. re-com) llaman a estas herramientas lanzando este servidor a través de MCP en lugar de hablar directamente con spotipy/Spotify — este es el único lugar donde viven las credenciales de Spotify.

Configuración

1. Registra una aplicación de Spotify

1. Ve al Spotify Developer Dashboard y crea una aplicación.

2. Añade una URI de redirección que coincida con SPOTIFY_REDIRECT_URI (por defecto http://127.0.0.1:8888/callback — no necesitas que nada escuche realmente en ese puerto; ver paso 3).

3. Anota el Client ID y el Client Secret de la aplicación.

2. Instala las dependencias

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

3. Autentícate

export SPOTIFY_CLIENT_ID="..."
export SPOTIFY_CLIENT_SECRET="..."
python scripts/setup_auth_spotify.py

Esto imprime una URL de autorización, espera a que inicies sesión y pegues la URL a la que te redirige (funciona bien a través de SSH/headless — no es necesario que nada enlace el puerto de redirección), y escribe el token resultante en .spotify_cache (ruta configurable mediante SPOTIFY_CACHE_PATH).

.spotify_cache equivale a tu sesión iniciada — nunca lo hagas commit ni lo compartas. Ya está en gitignore. Los tokens se renuevan automáticamente una vez en caché; vuelve a ejecutar este script solo si la renovación empieza a fallar (p. ej. se rotó el client secret de la aplicación, o revocaste el acceso desde los ajustes de tu cuenta de Spotify), o si SCOPE en server.py gana nuevos permisos (borra .spotify_cache primero para que el flujo de autenticación vuelva a pedir consentimiento — un token en caché obsoleto no recogerá nuevos scopes por sí mismo).

4. Añádelo a Claude Code

claude mcp add spotify -s user \
  -e SPOTIFY_CLIENT_ID="..." \
  -e SPOTIFY_CLIENT_SECRET="..." \
  -e SPOTIFY_CACHE_PATH="$(pwd)/.spotify_cache" \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

-s user lo hace disponible en cualquier sesión de Claude Code, no solo en este directorio. Usa rutas absolutas para el intérprete de Python, server.py y SPOTIFY_CACHE_PATH, ya que el servidor puede lanzarse desde cualquier directorio de trabajo.

Para otros clientes MCP (Claude Desktop, etc.), apúntalos al mismo comando y variables de entorno usando su formato de configuración respectivo.

Pruebas

La suite de pruebas unitarias (tests/) se ejecuta contra un cliente spotipy.Spotify falso hecho a mano — no se necesita acceso a la red ni credenciales de Spotify:

pip install -e ".[dev]"
pytest

Manejo de errores

Las llamadas a las herramientas convierten los modos de fallo comunes en mensajes claros en lugar de tracebacks crudos:

• Autenticación faltante/expirada (401) → te indica que repitas el paso de autenticación.

• Restringido/prohibido (403) → te indica que probablemente sea una restricción de acceso de la API de Spotify (ver la advertencia de recomendaciones/artistas relacionados arriba) o un scope OAuth faltante.

• Límite de tasa (429) → te indica que esperes, incluyendo la pista Retry-After si Spotify envió una.

• Cualquier otro error de API o OAuth se informa directamente, en lugar de como un traceback crudo.

Licencia

MIT — ver LICENSE.