SpotifyMCP

Un servidor MCP que envuelve la API web de Spotify, permitiendo a asistentes de IA (como Claude) controlar la reproducción, buscar en todo el catálogo incluyendo podcasts y audiolibros, gestionar tu biblioteca y listas de reproducción, y entender tus gustos musicales.

Por qué este

La mayoría de los servidores MCP de Spotify son envoltorios delgados. Este está diseñado para ser el predeterminado:

• Superficie de API completa — cada endpoint no obsoleto de la API web de Spotify que se puede llamar con un token de desarrollador estándar está cubierto por una herramienta (reproducción, búsqueda, catálogo, audiolibros, personalización, biblioteca, listas de reproducción, seguimiento).

• Honesto sobre las deprecaciones — Spotify eliminó recomendaciones, artistas relacionados, características/análisis de audio, semillas de género y listas destacadas de las nuevas aplicaciones. Los servidores que aún las exponen envían herramientas que fallan en tiempo de ejecución; este no.

• Probado — suite de pruebas unitarias completa sobre el cliente (refresco de token, limitación de tasa, paginación) y cada manejador de herramienta, además de una prueba de humo de protocolo MCP de extremo a extremo. Muchas alternativas tienen cero pruebas.

• Todo paginado — fetch_all en listados de biblioteca y listas de reproducción recorre cada página (limitado a 500 elementos) en lugar de truncar silenciosamente a una página de 50.

• Los podcasts son de primera clase — los episodios funcionan en todas partes: reproducción actual, cola, buscar y reproducir. Varios competidores no pueden ver podcasts en absoluto.

• Reproducción consciente de dispositivos — lista dispositivos, transfiere reproducción y apunta cualquier comando a un dispositivo específico para configuraciones de varias habitaciones.

• Autenticación robusta — flujo PKCE con refresco silencioso, caché de token persistente con modo 600, flujo de pegado sin cabeza (SPOTIFY_HEADLESS=1) para servidores y contenedores.

Related MCP server: Spotify MCP Server

Características

Reproducción (15 herramientas) — sondeos de reproducción actual / reproducción actual, reproducir (por URI, o play_from_search para reproducir directamente desde un nombre), pausa, saltar, anterior, buscar, volumen, aleatorio, repetir, ver/añadir cola, lista de dispositivos, transferir reproducción.

Búsqueda y catálogo — búsqueda unificada en pistas/artistas/álbumes/listas de reproducción/programas/episodios; búsquedas profundas para pistas, artistas, álbumes de artistas, álbumes, pistas de álbumes, programas, episodios de programas, episodios y tu perfil (get_me).

Audiolibros — títulos, capítulos, búsqueda de capítulos y tus audiolibros guardados (restringidos por mercado por Spotify a EE. UU./Reino Unido/Canadá/Irlanda/Nueva Zelanda/Australia).

Personalización — pistas y artistas principales en tres rangos de tiempo, reproducidos recientemente.

Biblioteca — pistas/álbumes/programas/episodios guardados con paginación completa opcional; guardar/eliminar/comprobar unificado mediante URIs /me/library.

Listas de reproducción — CRUD completo más gestión de elementos (añadir/eliminar/reordenar), recuperación de portada y carga de portada personalizada (se requiere el alcance ugc-image-upload para la carga).

Seguimiento — lista de artistas seguidos y comprobaciones de estado de seguimiento.

También se exponen: 7 recursos MCP (perfil, estado del reproductor, cola, pistas/artistas principales, reproducidos recientemente, listas de reproducción) y 4 plantillas de avisos (set de DJ, lista de ánimo, resumen de gustos, alternativa de descubrimiento).

Requisitos y limitaciones

• Se requiere Spotify Premium para el control de reproducción (reproducir, pausar, saltar, buscar, volumen, aleatorio, repetir, cola, transferir). Las cuentas gratuitas pueden autenticarse y usar herramientas de búsqueda/catálogo/biblioteca/listas de reproducción, pero cada comando de reproducción fallará con un error de Spotify que requiere Premium.

• La paginación de fetch_all recorre hasta 500 elementos por llamada (protege contra bucles descontrolados); más allá de eso, usa paginación limit/offset.

• Las herramientas de audiolibros están restringidas por mercado por Spotify a EE. UU., Reino Unido, Canadá, Irlanda, Nueva Zelanda y Australia.

• El modo de desarrollador de Spotify permite hasta 5 usuarios autorizados por aplicación hasta que se otorgue una cuota extendida.

Configuración rápida

1. Crear una aplicación de Spotify

Cada usuario necesita su propia aplicación de Spotify para obtener un ID de cliente — así es como Spotify identifica qué aplicación está haciendo solicitudes a la API.

1. Ve al Panel de desarrolladores de Spotify y crea una nueva aplicación.

2. En la configuración de la aplicación, añade la siguiente URI de redirección exactamente (Spotify rechazará el inicio de sesión si no coincide):

   http://127.0.0.1:8888/callback

3. Guarda. Copia tu ID de cliente.

2. Autenticarse

Ejecuta el comando a continuación una vez para iniciar sesión en tu cuenta de Spotify. Reemplaza your_client_id_here con el ID de cliente del paso 1. Abre una ventana del navegador y, después de que apruebes, guarda los tokens en ~/.spotify-mcp/tokens.json. El servidor los refresca automáticamente — no necesitarás hacer esto de nuevo.

macOS / Linux:

SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth

Hosts sin cabeza / remotos (sin navegador en la máquina que ejecuta el servidor MCP):

SPOTIFY_HEADLESS=1 SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth

La URL de autenticación se imprime; completa el flujo en cualquier navegador (por ejemplo, en tu portátil), luego pega la URL de redirección de vuelta en el aviso. Útil para homelabs, CI y tiempos de ejecución de agentes.

Autenticación sin cabeza (hosts sin navegador)

Si estás ejecutando este servidor MCP en un host que no tiene navegador (por ejemplo, una VM en la nube, un contenedor Docker, un servidor remoto), establece la variable de entorno SPOTIFY_HEADLESS=1. El flujo de autenticación omitirá el servidor de devolución de llamada HTTP local y en su lugar te pedirá que pegues la URL de redirección después de autorizar la aplicación en tu navegador.

Pasos

1. Establece SPOTIFY_HEADLESS=1 en tu entorno

2. Ejecuta el servidor — imprimirá una URL para autorizar la aplicación

3. Abre la URL en un navegador en una máquina diferente

4. Después de autorizar, tu navegador redirigirá a la URI de redirección

5. Copia la URL completa de la barra de direcciones

6. Pégala de vuelta en el aviso del servidor

Por qué

El flujo de autenticación predeterminado abre un navegador mediante el paquete open y ejecuta un servidor de devolución de llamada HTTP local en 127.0.0.1:8888. Eso se rompe cuando el servidor MCP se ejecuta en un host sin cabeza (homelab, CI, tiempo de ejecución de agente) donde no hay navegador para open(), y la devolución de llamada 127.0.0.1:8888 no puede ser alcanzada desde la máquina del usuario.

SPOTIFY_HEADLESS=1 cambia a un flujo de pegado de URL: la URL de autenticación se imprime en stdout, el operador completa el flujo en cualquier navegador (su portátil, teléfono), luego pega la URL de redirección completa de vuelta. El código + estado se extraen e intercambian en el lado del servidor. Funciona entre máquinas.

Windows (Símbolo del sistema):

set SPOTIFY_CLIENT_ID=your_client_id_here && npx -y @novalux12/spotify-mcp@latest auth

Windows (PowerShell):

$env:SPOTIFY_CLIENT_ID="your_client_id_here"; npx -y @novalux12/spotify-mcp@latest auth

3. Configurar Claude Desktop

Abre tu claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: Abre Claude Desktop → Configuración → Desarrollador → Editar configuración

Añade el bloque mcpServers (reemplaza your_client_id_here con tu ID de cliente):

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@novalux12/spotify-mcp@latest"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here"
      }
    }
  }
}

Sal por completo y reinicia Claude Desktop. Un icono de martillo en la entrada de chat confirma que el servidor está conectado.

Alternativa: Claude Code

Si usas Claude Code, añade el servidor sin editar JSON manualmente:

claude mcp add spotify -- npx -y @novalux12/spotify-mcp@latest
# then set SPOTIFY_CLIENT_ID in your shell or MCP env:
export SPOTIFY_CLIENT_ID=your_client_id_here

O añádelo a .mcp.json en la raíz de tu proyecto — misma forma command/args/env que arriba.

Comando para agentes de IA

Cualquier agente de codificación (Claude Code, OpenClaw, Cursor, Aider, …) puede instalar, compilar, autenticar y registrar el servidor en un solo pegado. Dale tu ID de cliente y déjalo ejecutar:

git clone https://github.com/NovaLux12/spotify-mcp-server.git && cd spotify-mcp-server \
  && npm ci && npm run build \
  && SPOTIFY_CLIENT_ID=your_client_id_here npm run auth

Luego apunta la configuración MCP de tu host a <repo>/dist/index.js con SPOTIFY_CLIENT_ID en su entorno (formas abajo). Los agentes deberían terminar llamando a la herramienta get_me una vez — prueba la autenticación, los alcances y el transporte en un solo viaje de ida y vuelta.

OpenClaw

Añade a mcp.servers en ~/.openclaw/openclaw.json:

"spotify": {
  "command": "node",
  "args": ["/path/to/spotify-mcp-server/dist/index.js"],
  "cwd": "/path/to/spotify-mcp-server",
  "env": { "SPOTIFY_CLIENT_ID": "your_client_id_here" }
}

Luego reinicia la puerta de enlace de OpenClaw para que reinicie el servidor. ¿Caja sin cabeza? Ejecuta el paso de autenticación con SPOTIFY_HEADLESS=1 en cualquier máquina con un navegador (ver arriba) — los tokens aterrizan en ~/.spotify-mcp/tokens.json de cualquier manera.

Cuando algo sale mal: instala la habilidad del doctor

Este repositorio incluye skills/spotify-mcp-doctor/SKILL.md — un diagnóstico procedimental que tu agente puede ejecutar en lugar de que tú releas este README. Recorre los modos de fallo reales en orden: cableado → binario → credenciales de la aplicación → frescura del token → clasificación de errores (Premium vs lista de permitidos del modo de desarrollo vs restricción de mercado vs deprecaciones). Instala:

cp -r skills/spotify-mcp-doctor ~/.openclaw/workspace/skills/   # OpenClaw
# or drop it into .claude/skills/ for Claude Code projects

Luego solo pregunta a tu agente: "Las herramientas de Spotify están fallando — ejecuta la habilidad del doctor de Spotify."

Uso

Una vez conectado, puedes preguntarle a Claude cosas como:

• "¿Cuáles son mis pistas principales de Spotify?"

• "Crea una lista de reproducción de canciones lo-fi relajadas para estudiar"

• "Añade la canción Blinding Lights a mi lista de reproducción de entrenamiento"

• "¿Qué artistas he estado escuchando más últimamente?"

• "Hazme una lista de reproducción con ambiente de conducir de noche"

Solución de problemas

• "No autenticado" en la primera llamada de herramienta — ejecuta npx -y @novalux12/spotify-mcp@latest auth (o npm run auth desde un clon) y completa el flujo del navegador. Los tokens se almacenan en ~/.spotify-mcp/tokens.json y se refrescan automáticamente.

• Discrepancia de URI de redirección — la URI de redirección de la aplicación de Spotify debe ser exactamente http://127.0.0.1:8888/callback (sin barra final). Guarda la configuración de la aplicación y reintenta.

• Puerto 8888 ocupado — otro proceso está sosteniendo el puerto de devolución de llamada; detenlo o elige un puerto libre mediante SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback con un puerto diferente y la configuración correspondiente en el Panel.

• Sin cabeza / Docker — establece SPOTIFY_HEADLESS=1 antes de auth; pega la URL de redirección de vuelta cuando se te pida (ver arriba).

Descargo de responsabilidad

Este es un proyecto personal, no afiliado ni respaldado por Spotify. Se proporciona tal cual, sin garantías de ningún tipo. Úsalo de manera responsable y de acuerdo con los Términos de servicio para desarrolladores de Spotify. El autor no es responsable de ningún uso indebido o consecuencias derivadas del uso de este software.

Desarrollo

git clone https://github.com/NovaLux12/spotify-mcp-server.git
cd spotify-mcp-server
npm install
npm run build

Copia .env.example a .env y completa tu ID de cliente, luego:

npm run auth   # authenticate with Spotify
npm run dev    # run from source (no build needed)

Requiere Node 22.9+ (soporte de --env-file-if-exists). No se necesita archivo .env — las variables de entorno provienen de tu configuración de host o de la línea de comandos.

Pruebas

npm test   # node:test runner — unit tests for the client and every tool module, plus an MCP protocol smoke test

Agradecimientos

• calebWei/SpotifyMCP — flujo de autenticación original y andamiaje de reproducción del que creció este proyecto.

• varunneal/spotify-mcp — la implementación de referencia utilizada como estándar de calidad para la cobertura de herramientas y la ergonomía.

Licencia

MIT © Carme99 y contribuyentes de NovaLux12.