Spotify MCP Server

Spotify Logo

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