Vulpes Spotify MCP Server

Servidor MCP de Spotify de Vuples

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a los asistentes de IA como Claude interactuar con Spotify, lo que les permite buscar y reproducir pistas.

Características

• Busque pistas por artista, título o cualquier consulta
• Reproduce pistas directamente en tu dispositivo Spotify activo
• Obtén información sobre la pista que estás reproduciendo actualmente
• Encuentra dispositivos de reproducción de Spotify disponibles
• Funcionalidad combinada de búsqueda y reproducción
• Lista de reproducción de Spotify del usuario
• Ver pistas dentro de las listas de reproducción
• Reproducir listas de reproducción (con modo aleatorio opcional)
• Buscar y reproducir listas de reproducción por nombre

Requisitos

• Node.js (v16+)
• Cuenta de desarrollador de Spotify
• Cuenta Spotify Premium (para funcionalidad de reproducción)
• Un cliente compatible con MCP (por ejemplo, Claude Desktop)

Instalación

1. Clonar este repositorio:
   git clone https://github.com/yourusername/spotify-mcp.git cd spotify-mcp
2. Instalar dependencias:
   npm install
3. Crea un archivo .env con tus credenciales de API de Spotify:
   SPOTIFY_CLIENT_ID=your_client_id SPOTIFY_CLIENT_SECRET=your_client_secret SPOTIFY_REDIRECT_URI=http://localhost:8888 # Optional: For playback control SPOTIFY_REFRESH_TOKEN=your_refresh_token
   Puede obtener su ID de cliente y su secreto desde el Panel de desarrolladores de Spotify .
4. Generar un token de actualización (necesario para el control de reproducción):Hay dos formas de obtener un token de actualización:Opción 1: utilizar el script incorporado
   npm run get-token
   Esto iniciará un servidor local y proporcionará instrucciones en la terminal.Opción 2: Utilice el script simple (si la opción 1 no funciona)
   node src/simple-auth.js
   Esto te dará una URL para abrir en tu navegador. Tras la autorización, serás redirigido a una URL. Copia esa URL de vuelta a la terminal y te mostrará un comando curl para obtener el token de actualización.Ámbitos obligatorios (ya incluidos en los scripts):
   • user-read-playback-state
   • user-modify-playback-state
   • user-read-currently-playing
   • playlist-read-private
   • playlist-read-collaborative
5. Agregue el token de actualización a su archivo .env :
   SPOTIFY_REFRESH_TOKEN=your_refresh_token
6. Construir el proyecto:
   npm run build

Uso con Claude Desktop

1. Primero, asegúrate de que Spotify esté abierto y reproduciéndose en tu dispositivo.
2. Agregue este servidor a su configuración de Claude Desktop:Edite su archivo claude_desktop_config.json (normalmente en ~/Library/Application Support/Claude/ en macOS o %APPDATA%\\Claude\\ en Windows):
   { "mcpServers": { "spotify": { "command": "node", "args": ["/absolute/path/to/vulpes-spotify-mcp/dist/index.js"], "env": { "SPOTIFY_CLIENT_ID": "your_client_id", "SPOTIFY_CLIENT_SECRET": "your_client_secret", "SPOTIFY_REDIRECT_URI": "http://localhost:8888", "SPOTIFY_REFRESH_TOKEN": "your_refresh_token" } } } }
   Asegúrate de reemplazar /absolute/path/to/vulpes-spotify-mcp con la ruta real a tu proyecto.
3. Reiniciar Claude Desktop
4. Ahora deberías ver las herramientas de Spotify disponibles cuando haces clic en el ícono del martillo en Claude Desktop

Herramientas disponibles

• spotify-search : busca pistas por consulta
• spotify-play : Reproduce una pista específica por ID o URI
• spotify-currently-playing : obtener información sobre la pista que se está reproduciendo actualmente
• spotify-devices : Lista de dispositivos de reproducción de Spotify disponibles
• spotify-search-and-play : busca una pista y reproduce automáticamente el resultado principal
• spotify-playlists : Obtenga una lista de las listas de reproducción de Spotify del usuario
• spotify-playlist-tracks : Obtener pistas de una lista de reproducción específica
• spotify-play-playlist : Reproduce una lista de reproducción específica (con reproducción aleatoria opcional)
• spotify-find-playlist : busca una lista de reproducción por nombre y reprodúcela (recomendado para uso con IA)

Solución de problemas

• "No se encontró ningún dispositivo activo" : asegúrate de que Spotify esté abierto y reproduciéndose en al menos uno de tus dispositivos
• "Permisos faltantes" : es posible que su token de actualización no tenga los alcances requeridos
• "No premium" : El control de reproducción requiere una cuenta Spotify Premium
• "Problemas con el token de actualización" : si su token caduca, genere uno nuevo siguiendo los pasos de la sección de instalación.

Notas importantes

1. Asegúrese siempre de que Spotify esté abierto en al menos un dispositivo antes de usar los controles de reproducción
2. El token de actualización en su archivo .env y la configuración de Claude Desktop deben coincidir
3. Después de realizar cambios en su configuración, reinicie Claude Desktop

Licencia

Instituto Tecnológico de Massachusetts (MIT)