MCP Claude Spotify

Características

• Autenticación de Spotify
• Buscar pistas, álbumes, artistas y listas de reproducción
• Control de reproducción (reproducir, pausar, siguiente, anterior)
• Crear y administrar listas de reproducción
• Obtenga recomendaciones personalizadas
• Acceda a las pistas más reproducidas del usuario durante diferentes períodos de tiempo

Manifestación

Requisitos

• Node.js 16 o superior
• Cuenta de Spotify
• Escritorio de Claude
• Credenciales de la API de Spotify (ID de cliente y secreto de cliente)

Instalación

Instalación mediante herrería

Para instalar MCP Claude Spotify para Claude Desktop automáticamente a través de Smithery :

Instalación manual

1. Clonar o descargar este repositorio:

2. Instalar dependencias:

3. Construye el proyecto (si quieres modificar el código fuente):

El repositorio ya incluye archivos precompilados en el directorio build , por lo que puede omitir el paso 3 si no planea modificar el código fuente.

Configuración de credenciales de Spotify

Para utilizar este MCP, necesita obtener las credenciales de la API de Spotify:

1. Ir al panel de desarrolladores de Spotify
2. Inicia sesión con tu cuenta de Spotify
3. Haga clic en "Crear aplicación"
4. Complete la información de su aplicación:
   • Nombre de la aplicación: "MCP Claude Spotify" (o el que prefieras)
   • Descripción de la aplicación: "Integración de Spotify con Claude Desktop"
   • Sitio web: Puede dejar este campo en blanco o poner cualquier URL
   • URI de redireccionamiento: Importante : agregue http://127.0.0.1:8888/callback
5. Acepte los términos y condiciones y haga clic en "Crear"
6. En el panel de tu aplicación, verás el "ID del cliente".
7. Haga clic en "Mostrar secreto de cliente" para revelar su "secreto de cliente".

Guarde estas credenciales ya que las necesitará para la configuración.

Ejecución del servidor MCP

Hay dos formas de ejecutar el servidor MCP:

Opción 1: Ejecutar manualmente (recomendado para la primera configuración y resolución de problemas)

1. Abra una terminal o un símbolo del sistema
2. Navegar al directorio del proyecto
3. Ejecute el servidor directamente:

Mantenga esta ventana de terminal abierta mientras usa Claude Desktop. El servidor se ejecutará hasta que cierre la terminal.

Opción 2: Inicio automático con Claude Desktop (recomendado para uso habitual)

El Escritorio Claude puede iniciar automáticamente el servidor MCP cuando sea necesario. Para configurarlo:

Configuración

El archivo de configuración de Claude Desktop se encuentra en:

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
• Ventanas : %APPDATA%\Claude\claude_desktop_config.json

Edite este archivo para agregar la configuración de Spotify MCP. Si el archivo no existe, créelo:

Importante : Reemplazar:

• ABSOLUTE_PATH_TO_DIRECTORY con la ruta absoluta completa donde instaló el MCP
  • Ejemplo de macOS/Linux: /Users/username/mcp-claude-spotify
  • Ejemplo de Windows: C:\\Users\\username\\mcp-claude-spotify
• your_client_id_here con el ID de cliente que obtuviste de Spotify
• your_client_secret_here con el secreto de cliente que obtuviste de Spotify

Si ya tiene otros MCP configurados, simplemente agregue la sección "spotify" dentro del objeto "mcpServers".

Configuración de scripts de inicio automático (opcional)

Para una experiencia más confiable, puede configurar scripts de inicio automático:

1. Crea un archivo llamado start-spotify-mcp.bat en el directorio del proyecto con el siguiente contenido:

2. Crea un acceso directo a este archivo BAT
3. Presione Win+R , escriba shell:startup y presione Enter
4. Mueva el acceso directo a esta carpeta para que se inicie con Windows
5. Crea un archivo llamado com.spotify.mcp.plist en ~/Library/LaunchAgents/ con el siguiente contenido:

2. Reemplace la ruta y las credenciales con sus valores reales
3. Cargue el agente con: launchctl load ~/Library/LaunchAgents/com.spotify.mcp.plist
4. Crea un archivo llamado spotify-mcp.service en ~/.config/systemd/user/ (crea el directorio si no existe):

2. Reemplace la ruta y las credenciales con sus valores reales
3. Habilitar e iniciar el servicio:

4. Comprobar estado con:

Uso

1. Reinicie Claude Desktop después de modificar la configuración
2. En Claude, use el comando auth-spotify para iniciar el proceso de autenticación
3. Se abrirá una ventana del navegador para que autorices la aplicación.
4. Inicia sesión con tu cuenta de Spotify y autoriza la aplicación
5. Importante : después de una autenticación exitosa, reinicie Claude Desktop para inicializar correctamente el registro de herramientas de MCP y el caché de token de sesión WebSocket.
6. Después de reiniciar, todas las herramientas de Spotify MCP estarán correctamente registradas y disponibles para su uso.

El servidor MCP se ejecuta como un proceso secundario administrado por Claude Desktop. Cuando Claude se ejecuta, inicia y administra automáticamente el proceso del servidor Node.js según la configuración de claude_desktop_config.json .

Herramientas disponibles

autenticación de spotify

Inicia el proceso de autenticación de Spotify.

búsqueda-spotify

Busca pistas, álbumes, artistas o listas de reproducción.

Parámetros:

• query : Buscar texto
• type : Tipo de búsqueda (pista, álbum, artista, lista de reproducción)
• limit : Número de resultados (1-50)

pista de reproducción

Reproduce una pista específica.

Parámetros:

• trackId : ID de pista de Spotify
• deviceId : (opcional) ID del dispositivo de Spotify para reproducir

obtener reproducción actual

Obtiene información sobre la reproducción actual.

pausa-reproducción

Pausa la reproducción.

siguiente pista

Salta a la siguiente pista.

pista anterior

Regresa a la pista anterior.

obtener listas de reproducción de usuario

Obtiene las listas de reproducción del usuario.

crear lista de reproducción

Crea una nueva lista de reproducción.

Parámetros:

• name : Nombre de la lista de reproducción
• description : (Opcional) Descripción
• public : (opcional) si es público o privado

añadir pistas a la lista de reproducción

Agrega pistas a una lista de reproducción.

Parámetros:

• playlistId : ID de lista de reproducción
• trackIds : Matriz de identificadores de pistas

obtener recomendaciones

Obtiene recomendaciones basadas en semillas.

Parámetros:

• seedTracks : (opcional) Matriz de identificaciones de pistas
• seedArtists : (opcional) Matriz de identificaciones de artistas
• seedGenres : (Opcional) Matriz de géneros
• limit : (opcional) Número de recomendaciones (1-100)

obtener las mejores pistas

Obtiene las pistas más reproducidas del usuario durante un rango de tiempo específico.

Parámetros:

• limit : (opcional) Número de pistas a devolver (1-50, predeterminado: 20)
• offset : (opcional) Índice de la primera pista a devolver (predeterminado: 0)
• time_range : (opcional) Intervalo de tiempo para calcular la afinidad:
  • short_term : Aproximadamente las últimas 4 semanas
  • medium_term : Aproximadamente los últimos 6 meses (predeterminado)
  • long_term : Varios años de datos

Solución de problemas

Error "Servidor desconectado"

Si ves el error "MCP Spotify: Servidor desconectado" en Claude Desktop:

1. Verifique que el servidor esté ejecutándose :
   • Abra una terminal y ejecute manualmente node build/index.js desde el directorio del proyecto
   • Si el servidor se inicia correctamente, utilice Claude mientras mantiene esta terminal abierta
2. Comprueba tu configuración :
   • Asegúrese de que la ruta absoluta en claude_desktop_config.json sea correcta para su sistema
   • Verifique nuevamente que haya utilizado barras invertidas dobles ( \\ ) para las rutas de Windows
   • Verifique que esté utilizando la ruta completa desde la raíz de su sistema de archivos
3. Pruebe la opción de inicio automático :
   • Configure el script de inicio automático para su sistema operativo como se describe en la sección "Configuración de scripts de inicio automático".
   • Esto garantiza que el servidor siempre esté funcionando cuando lo necesite.

El navegador no se abre automáticamente

Si el navegador no se abre automáticamente durante la autenticación, visite manualmente: http://127.0.0.1:8888/login

Error de autenticación

Asegúrate de haber configurado correctamente la URI de redireccionamiento en tu panel de desarrollador de Spotify: http://127.0.0.1:8888/callback

Error de inicio del servidor

Verificar que:

• Las variables de entorno están configuradas correctamente en su claude_desktop_config.json o en el script de inicio
• Node.js está instalado y es compatible (v16+)
• Los puertos requeridos (8888) están disponibles y no están bloqueados por el firewall
• Tienes permiso para ejecutar el script en la ubicación especificada

Herramientas que no aparecen en Claude

Si las herramientas de Spotify no aparecen en Claude después de la autenticación:

• Asegúrese de haber reiniciado Claude Desktop después de una autenticación exitosa
• Verifique los registros de Claude Desktop para detectar cualquier error de comunicación de MCP
• Asegúrese de que el proceso del servidor MCP se esté ejecutando (ejecútelo manualmente para confirmarlo)
• Verifique que el servidor MCP esté registrado correctamente en el registro de MCP de Claude Desktop

Comprobando si el servidor está funcionando

Para comprobar si el servidor está funcionando:

• Windows : Abra el Administrador de tareas, vaya a la pestaña "Detalles" y busque "node.exe"
• macOS/Linux : Abra la Terminal y ejecute ps aux | grep node

Si no ve el servidor en ejecución, inícielo manualmente o utilice el método de inicio automático.

Pruebas

Este proyecto incluye pruebas automatizadas para garantizar la calidad y funcionalidad del código. El conjunto de pruebas utiliza Jest compatible con TypeScript y cubre:

• Validación de esquemas Zod: verifica que todos los esquemas de entrada validen correctamente los datos
• Interacciones de la API de Spotify: prueba el manejo de solicitudes de API y el manejo de errores
• Funcionalidad del servidor MCP: garantiza el registro y la ejecución adecuados de las herramientas

Ejecución de pruebas

Primero, asegúrese de que todas las dependencias de desarrollo estén instaladas:

Para ejecutar todas las pruebas:

Para ejecutar un archivo de prueba específico:

Si encuentra problemas con los módulos ESM, asegúrese de estar usando Node.js v16 o superior y de que la variable de entorno NODE_OPTIONS incluya el indicador --experimental-vm-modules tal como está configurado en package.json.

Estructura de la prueba

• tests/schemas.test.ts : Pruebas para esquemas de validación de entrada
• tests/spotify-api.test.ts : Pruebas para interacciones de la API de Spotify
• tests/server.test.ts : Pruebas de la funcionalidad del servidor MCP

Agregar nuevas pruebas

Al agregar nueva funcionalidad, incluya las pruebas correspondientes:

1. Para esquemas nuevos, agregue pruebas de validación en schemas.test.ts
2. Para las funciones de la API de Spotify, agregue pruebas en spotify-api.test.ts
3. Para las herramientas MCP, agregue pruebas en server.test.ts

Todas las pruebas deben escribirse utilizando Jest y el formato del módulo ESM con TypeScript.

Notas de seguridad

• Nunca comparta su ID de cliente ni su secreto de cliente
• El token de acceso ahora se almacena en el directorio de inicio del usuario en ~/.spotify-mcp/tokens.json para permitir la persistencia entre sesiones y múltiples instancias
• No se almacenan datos de usuario en el disco

Revocar el acceso a la aplicación

Por razones de seguridad, es posible que desees revocar el acceso de la aplicación a tu cuenta de Spotify cuando:

• Ya no utilizas esta integración
• Sospecha de un acceso no autorizado
• Estás solucionando problemas de autenticación

Para revocar el acceso:

1. Ve a la página de tu cuenta de Spotify
2. Vaya a "Aplicaciones" en el menú.
3. Busca "MCP Claude Spotify" (o el nombre que elegiste para tu aplicación)
4. Haga clic en "QUITAR ACCESO"

Esto invalida inmediatamente todos los tokens de acceso y actualización. La próxima vez que uses el comando auth-spotify , tendrás que volver a autorizar la aplicación.

Contribuyendo

¡Agradecemos sus contribuciones! Aquí hay algunas pautas a seguir:

Flujo de trabajo de desarrollo

1. Bifurcar el repositorio
2. Crear una rama de características ( git checkout -b feature/amazing-feature )
3. Realiza tus cambios
4. Ejecutar pruebas para garantizar que pasen ( npm test )
5. Confirme sus cambios ( git commit -m 'Add some amazing feature' )
6. Empujar a la rama ( git push origin feature/amazing-feature )
7. Abrir una solicitud de extracción

Pautas de estilo de código

Este proyecto sigue estos estándares de codificación:

• Utilice TypeScript con verificación de tipos estricta
• Seguir el formato del módulo ESM
• Utilice 2 espacios para la sangría
• Utilice camelCase para variables y funciones
• Utilice PascalCase para clases e interfaces
• Funciones de documentos con comentarios JSDoc
• Mantenga la longitud de línea por debajo de 100 caracteres

Estructura del proyecto

El proyecto sigue la siguiente estructura:

Proceso de solicitud de extracción

1. Asegúrese de que su código siga las pautas de estilo
2. Actualice la documentación si es necesario
3. Agregar pruebas para nuevas funcionalidades
4. Asegúrese de que todas las pruebas pasen
5. Su PR será revisado por los mantenedores

Enlaces relacionados

• Protocolo de contexto modelo
• Documentación de la API web de Spotify
• Escritorio de Claude

Licencia

Este proyecto está licenciado bajo la Licencia Pública de Mozilla 2.0: consulte el archivo de LICENCIA para obtener más detalles.