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
git clone https://github.com/Yonsn76/spotify-mcp.git
cd spotify-mcp
npm install
npm run build
2. Obtener credenciales de Spotify
- Ve a Spotify Developer Dashboard
- 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:
spotifyAuth(accion="configurar", clientId="tu_client_id", clientSecret="tu_client_secret")
Las credenciales se guardan en ~/.spotify-mcp-tokens.json junto con los tokens de sesion.
Instalacion por IDE
Kiro
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:
{
"mcpServers": {
"spotify": {
"command": "npx",
"args": ["tsx", "RUTA/AL/PROYECTO/src/index.ts"],
"env": {
"SPOTIFY_CLIENT_ID": "tu_client_id",
"SPOTIFY_CLIENT_SECRET": "tu_client_secret",
"SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8000/callback"
}
}
}
}
VS Code
Edita tu archivo de configuracion MCP:
{
"mcpServers": {
"spotify": {
"command": "npx",
"args": ["tsx", "RUTA/AL/PROYECTO/src/index.ts"],
"env": {
"SPOTIFY_CLIENT_ID": "tu_client_id",
"SPOTIFY_CLIENT_SECRET": "tu_client_secret",
"SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8000/callback"
}
}
}
}
Cursor
- Abre Settings (Ctrl+Shift+J o Cmd+Shift+J)
- Ve a la seccion MCP
- Agrega el servidor:
{
"mcpServers": {
"spotify": {
"command": "npx",
"args": ["tsx", "RUTA/AL/PROYECTO/src/index.ts"],
"env": {
"SPOTIFY_CLIENT_ID": "tu_client_id",
"SPOTIFY_CLIENT_SECRET": "tu_client_secret",
"SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8000/callback"
}
}
}
}
Claude Desktop
Edita el archivo de configuracion:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"spotify": {
"command": "npx",
"args": ["tsx", "RUTA/AL/PROYECTO/src/index.ts"],
"env": {
"SPOTIFY_CLIENT_ID": "tu_client_id",
"SPOTIFY_CLIENT_SECRET": "tu_client_secret",
"SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8000/callback"
}
}
}
}
Reinicia Claude Desktop despues de guardar.
Windsurf
Agrega a tu configuracion MCP:
{
"mcpServers": {
"spotify": {
"command": "npx",
"args": ["tsx", "RUTA/AL/PROYECTO/src/index.ts"],
"env": {
"SPOTIFY_CLIENT_ID": "tu_client_id",
"SPOTIFY_CLIENT_SECRET": "tu_client_secret",
"SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8000/callback"
}
}
}
}
Autenticacion
Una vez configurado el servidor MCP:
- Usa
spotifyAuth(accion="verificar")para ver el estado actual - Si 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 |
|---|---|
verificar | Comprueba estado de autenticacion (usar primero) |
configurar | Guarda clientId y clientSecret |
ejecutar | Completa flujo OAuth automatico |
iniciar | Abre navegador para auth manual |
urlAuth | Obtiene URL de autorizacion |
cerrar | Cierra sesion |
spotifyPlayer - Control de Reproduccion
| Accion | Parametros | Descripcion |
|---|---|---|
play | tipo, id o uri | Reproduce contenido |
pause | - | Pausa reproduccion |
resume | - | Reanuda reproduccion |
next | - | Siguiente cancion |
prev | - | Cancion anterior |
volume | valor (0-100) | Ajusta volumen |
shuffle | valor (bool) | Activa/desactiva aleatorio |
repeat | valor (track/context/off) | Modo repeticion |
seek | valor (ms) | Salta a posicion |
queue | tipo, id o uri | Agrega a la cola |
transfer | dispositivo | Cambia dispositivo |
playLiked | valor (bool=shuffle) | Reproduce Me gusta |
openApp | valor (bool=web) | Abre Spotify |
spotifyInfo - Busqueda e Informacion
| Accion | Parametros | Descripcion |
|---|---|---|
search | consulta, tipo | Busca contenido |
nowPlaying | - | Cancion actual |
devices | - | Lista dispositivos |
profile | - | Perfil del usuario |
queue | - | Cola de reproduccion |
history | limite | Canciones recientes |
saved | limite, offset | Canciones guardadas |
playlists | limite | Playlists del usuario |
playlistTracks | id, limite | Canciones de playlist |
albumTracks | id, limite | Canciones de album |
artistTop | id, mercado | Top de artista |
topTracks | periodo, limite | Tus canciones top |
topArtists | periodo, limite | Tus artistas top |
state | - | Estado de reproduccion |
spotifyLibrary - Gestion de Biblioteca
| Accion | Parametros | Descripcion |
|---|---|---|
save | ids | Guarda canciones en Me gusta |
remove | ids | Quita de Me gusta |
check | ids | Verifica si estan guardadas |
createPlaylist | nombre, descripcion, publica | Crea playlist |
addToPlaylist | playlistId, ids, posicion | Agrega a playlist |
removeFromPlaylist | playlistId, ids | Quita de playlist |
deletePlaylist | playlistId | Elimina playlist |
renamePlaylist | 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.json - Los tokens se refrescan automaticamente
- El Redirect URI debe coincidir exactamente en el Dashboard y la configuracion
Solucion de Problemas
Error: Credenciales no configuradas
Usa spotifyAuth(accion="configurar", clientId="...", clientSecret="...") o agrega las variables de entorno en el mcp.json.
Error: No hay dispositivo activo
- Verifica dispositivos con
spotifyInfo(accion="devices") - Si no hay ninguno, abre Spotify con
spotifyPlayer(accion="openApp") - Reproduce algo manualmente para activar la sesion
Error: Premium requerido
El control de reproduccion requiere Spotify Premium. Las funciones de busqueda e informacion funcionan con cuentas gratuitas.
Error: INVALID_CLIENT
- 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
Error: EADDRINUSE (puerto ocupado)
El puerto 8000 esta en uso.
Windows:
netstat -ano | findstr :8000
taskkill /PID [PID] /F
Linux/macOS:
lsof -i :8000
kill -9 [PID]
Las herramientas no responden
Si ninguna herramienta del player funciona:
- Abre Spotify manualmente
- Reproduce cualquier cancion
- Ahora las herramientas deberian funcionar