Spotify MCP Server

<p align="center"> <img src="https://storage.googleapis.com/pr-newsroom-wp/1/2023/05/Spotify_Primary_Logo_RGB_Green.png" width="200" alt="Spotify Logo"> </p>

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

1. Ve a Spotify Developer Dashboard
2. Crea una nueva aplicacion
3. Copia el Client ID y Client Secret
4. 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

<details> <summary><strong>Kiro</strong></summary>

Opcion 1: Importar Power (recomendado)

1. Abre Kiro
2. Ve al panel de Powers
3. Clic en "Import Local Power"
4. 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"
      }
    }
  }
}

</details>

<details> <summary><strong>VS Code</strong></summary>

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"
      }
    }
  }
}

</details>

<details> <summary><strong>Cursor</strong></summary>

1. Abre Settings (Ctrl+Shift+J o Cmd+Shift+J)
2. Ve a la seccion MCP
3. 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"
      }
    }
  }
}

</details>

<details> <summary><strong>Claude Desktop</strong></summary>

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.

</details>

<details> <summary><strong>Windsurf</strong></summary>

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"
      }
    }
  }
}

</details>

Autenticacion

Una vez configurado el servidor MCP:

1. Usa spotifyAuth(accion="verificar") para ver el estado actual
2. Si no hay credenciales, configuralas con spotifyAuth(accion="configurar", clientId="...", clientSecret="...")
3. 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:

1. El servidor MCP puede no responder correctamente
2. Solucion: Reproduce cualquier cancion manualmente en Spotify
3. Una vez que haya musica sonando (aunque este pausada), las herramientas funcionaran

Flujo Recomendado para Reproducir

1. Verificar dispositivos: spotifyInfo(accion="devices")
2. Si no hay dispositivos: spotifyPlayer(accion="openApp")
3. Esperar a que Spotify cargue y reproducir algo manualmente
4. Buscar contenido: spotifyInfo(accion="search", consulta="...", tipo="track")
5. 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

<details> <summary><strong>Error: Credenciales no configuradas</strong></summary>

Usa spotifyAuth(accion="configurar", clientId="...", clientSecret="...") o agrega las variables de entorno en el mcp.json.

</details>

<details> <summary><strong>Error: No hay dispositivo activo</strong></summary>

1. Verifica dispositivos con spotifyInfo(accion="devices")
2. Si no hay ninguno, abre Spotify con spotifyPlayer(accion="openApp")
3. Reproduce algo manualmente para activar la sesion

</details>

<details> <summary><strong>Error: Premium requerido</strong></summary>

El control de reproduccion requiere Spotify Premium. Las funciones de busqueda e informacion funcionan con cuentas gratuitas.

</details>

<details> <summary><strong>Error: INVALID_CLIENT</strong></summary>

• 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

</details>

<details> <summary><strong>Error: EADDRINUSE (puerto ocupado)</strong></summary>

El puerto 8000 esta en uso.

Windows:

netstat -ano | findstr :8000
taskkill /PID [PID] /F

Linux/macOS:

lsof -i :8000
kill -9 [PID]

</details>

<details> <summary><strong>Las herramientas no responden</strong></summary>

Si ninguna herramienta del player funciona:

1. Abre Spotify manualmente
2. Reproduce cualquier cancion
3. Ahora las herramientas deberian funcionar

</details>