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

Related MCP server: Spotify MCP Node Server

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

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

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

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

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.

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:

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

spotifyPlayer - Control de Reproduccion

spotifyInfo - Busqueda e Informacion

spotifyLibrary - Gestion de Biblioteca

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

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

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

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:

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

Linux/macOS:

lsof -i :8000
kill -9 [PID]

Si ninguna herramienta del player funciona:

1. Abre Spotify manualmente

2. Reproduce cualquier cancion

3. Ahora las herramientas deberian funcionar