Spotify MCP Server

# 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 ```bash 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](https://developer.spotify.com/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`: ```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: ```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>Cursor</strong></summary> 1. Abre Settings (Ctrl+Shift+J o Cmd+Shift+J) 2. Ve a la seccion MCP 3. Agrega el servidor: ```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>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` ```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: ```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> ## 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: ```cmd netstat -ano | findstr :8000 taskkill /PID [PID] /F ``` Linux/macOS: ```bash 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>