Provides comprehensive control of Spotify playback, search, and library management, including playing tracks/albums/playlists, controlling playback (play/pause/skip/volume/shuffle/repeat), searching content, managing playlists, saving tracks to library, viewing playback history, and accessing user profile information. Requires Spotify Premium for playback control features.
Spotify MCP Server
Servidor MCP (Model Context Protocol) para controlar Spotify desde asistentes de IA como Claude, Cursor, Kiro, VS Code, Windsurf, etc.
Requisitos
Node.js 18+
Cuenta de Spotify Premium (requerido para control de reproduccion)
Credenciales de la API de Spotify
Configuracion Inicial
1. Clonar el proyecto
2. Obtener credenciales de Spotify
Crea una nueva aplicacion
Copia el Client ID y Client Secret
En "Edit Settings", agrega como Redirect URI:
http://127.0.0.1:8000/callback
3. Configurar credenciales
Hay dos formas de configurar las credenciales:
Opcion A: Variables de entorno en mcp.json (recomendado para configuracion inicial)
Agrega las credenciales en el archivo de configuracion MCP de tu IDE.
Opcion B: Configuracion por el LLM
Puedes pedirle al asistente que configure las credenciales usando:
Las credenciales se guardan en ~/.spotify-mcp-tokens.json junto con los tokens de sesion.
Instalacion por IDE
Opcion 1: Importar Power (recomendado)
Abre Kiro
Ve al panel de Powers
Clic en "Import Local Power"
Selecciona la carpeta
power-kiro/de este proyecto
Opcion 2: Configuracion manual
Edita .kiro/settings/mcp.json:
Edita tu archivo de configuracion MCP:
Abre Settings (Ctrl+Shift+J o Cmd+Shift+J)
Ve a la seccion MCP
Agrega el servidor:
Edita el archivo de configuracion:
Windows:
%APPDATA%\Claude\claude_desktop_config.jsonmacOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Reinicia Claude Desktop despues de guardar.
Agrega a tu configuracion MCP:
Autenticacion
Una vez configurado el servidor MCP:
Usa
spotifyAuth(accion="verificar")para ver el estado actualSi no hay credenciales, configuralas con
spotifyAuth(accion="configurar", clientId="...", clientSecret="...")Usa
spotifyAuth(accion="ejecutar")para completar el flujo OAuth (abre navegador automaticamente)
Herramientas Disponibles
El servidor expone 4 herramientas consolidadas:
spotifyAuth - Autenticacion
Accion | Descripcion |
| Comprueba estado de autenticacion (usar primero) |
| Guarda clientId y clientSecret |
| Completa flujo OAuth automatico |
| Abre navegador para auth manual |
| Obtiene URL de autorizacion |
| Cierra sesion |
spotifyPlayer - Control de Reproduccion
Accion | Parametros | Descripcion |
| tipo, id o uri | Reproduce contenido |
| - | Pausa reproduccion |
| - | Reanuda reproduccion |
| - | Siguiente cancion |
| - | Cancion anterior |
| valor (0-100) | Ajusta volumen |
| valor (bool) | Activa/desactiva aleatorio |
| valor (track/context/off) | Modo repeticion |
| valor (ms) | Salta a posicion |
| tipo, id o uri | Agrega a la cola |
| dispositivo | Cambia dispositivo |
| valor (bool=shuffle) | Reproduce Me gusta |
| valor (bool=web) | Abre Spotify |
spotifyInfo - Busqueda e Informacion
Accion | Parametros | Descripcion |
| consulta, tipo | Busca contenido |
| - | Cancion actual |
| - | Lista dispositivos |
| - | Perfil del usuario |
| - | Cola de reproduccion |
| limite | Canciones recientes |
| limite, offset | Canciones guardadas |
| limite | Playlists del usuario |
| id, limite | Canciones de playlist |
| id, limite | Canciones de album |
| id, mercado | Top de artista |
| periodo, limite | Tus canciones top |
| periodo, limite | Tus artistas top |
| - | Estado de reproduccion |
spotifyLibrary - Gestion de Biblioteca
Accion | Parametros | Descripcion |
| ids | Guarda canciones en Me gusta |
| ids | Quita de Me gusta |
| ids | Verifica si estan guardadas |
| nombre, descripcion, publica | Crea playlist |
| playlistId, ids, posicion | Agrega a playlist |
| playlistId, ids | Quita de playlist |
| playlistId | Elimina playlist |
| playlistId, nombre | Renombra playlist |
Notas Importantes
Sesion de Reproduccion Activa
Spotify requiere que haya una sesion de reproduccion activa para que las herramientas de control funcionen. Si acabas de abrir Spotify sin reproducir nada:
El servidor MCP puede no responder correctamente
Solucion: Reproduce cualquier cancion manualmente en Spotify
Una vez que haya musica sonando (aunque este pausada), las herramientas funcionaran
Flujo Recomendado para Reproducir
Verificar dispositivos:
spotifyInfo(accion="devices")Si no hay dispositivos:
spotifyPlayer(accion="openApp")Esperar a que Spotify cargue y reproducir algo manualmente
Buscar contenido:
spotifyInfo(accion="search", consulta="...", tipo="track")Reproducir:
spotifyPlayer(accion="play", tipo="track", id="ID_OBTENIDO")
Almacenamiento
Credenciales y tokens se guardan en
~/.spotify-mcp-tokens.jsonLos tokens se refrescan automaticamente
El Redirect URI debe coincidir exactamente en el Dashboard y la configuracion
Solucion de Problemas
Usa spotifyAuth(accion="configurar", clientId="...", clientSecret="...") o agrega las variables de entorno en el mcp.json.
Verifica dispositivos con
spotifyInfo(accion="devices")Si no hay ninguno, abre Spotify con
spotifyPlayer(accion="openApp")Reproduce algo manualmente para activar la sesion
El control de reproduccion requiere Spotify Premium. Las funciones de busqueda e informacion funcionan con cuentas gratuitas.
Verifica que Client ID y Client Secret sean correctos
Confirma que el Redirect URI en el Dashboard sea exactamente
http://127.0.0.1:8000/callback
El puerto 8000 esta en uso.
Windows:
Linux/macOS:
Si ninguna herramienta del player funciona:
Abre Spotify manualmente
Reproduce cualquier cancion
Ahora las herramientas deberian funcionar