MCP Claude Spotify

MCP Claude Spotify

Una integración que permite a Claude Desktop interactuar con Spotify mediante el Protocolo de Contexto de Modelo (MCP).

Características

• Autenticación de Spotify
• Búsqueda de canciones, álbumes, artistas y listas de reproducción
• Control de reproducción (reproducir, pausar, siguiente, anterior)
• Gestión completa de listas de reproducción (crear, actualizar, eliminar, reordenar canciones, gestionar imágenes de portada)
• Obtener recomendaciones personalizadas
• Acceder a las canciones más reproducidas del usuario en diferentes períodos de tiempo
• Ver canciones reproducidas recientemente

Demo

Requisitos

• Node.js 16 o superior
• Cuenta de Spotify
• Claude Desktop
• Credenciales de la API de Spotify (Client ID y Client Secret)

Instalación

Instalación mediante Smithery

Para instalar MCP Claude Spotify para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @imprvhub/mcp-claude-spotify --client claude

Instalación manual

1. Clona o descarga este repositorio:

git clone https://github.com/imprvhub/mcp-claude-spotify
cd claude-spotify-mcp

2. Instala las dependencias:

npm install

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

npm run build

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

Configuración de las credenciales de Spotify

Para usar este MCP, necesitas obtener las credenciales de la API de Spotify:

1. Ve al Panel de desarrolladores de Spotify
2. Inicia sesión con tu cuenta de Spotify
3. Haz clic en "Create App"
4. Completa la información de tu aplicación:
   • App name: "MCP Claude Spotify" (o el nombre que prefieras)
   • App description: "Spotify integration for Claude Desktop"
   • Website: Puedes dejarlo en blanco o poner cualquier URL
   • Redirect URI: Importante - Añade http://127.0.0.1:8888/callback
5. Acepta los términos y condiciones y haz clic en "Create"
6. En el panel de tu aplicación, verás el "Client ID"
7. Haz clic en "Show Client Secret" para revelar tu "Client Secret"

Guarda estas credenciales, ya que las necesitarás para la configuración.

Ejecución del servidor MCP

Hay dos formas de ejecutar el servidor MCP:

Opción 1: Ejecución manual (recomendada para la configuración inicial y resolución de problemas)

1. Abre una terminal o símbolo del sistema
2. Navega al directorio del proyecto
3. Ejecuta el servidor directamente:

node build/index.js

Mantén esta ventana de terminal abierta mientras usas Claude Desktop. El servidor se ejecutará hasta que cierres la terminal.

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

Claude Desktop 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
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Edita este archivo para añadir la configuración del MCP de Spotify. Si el archivo no existe, créalo:

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Importante: Reemplaza:

• ABSOLUTE_PATH_TO_DIRECTORY con la ruta absoluta completa donde instalaste el MCP
  • Ejemplo en macOS/Linux: /Users/username/mcp-claude-spotify
  • Ejemplo en Windows: C:\\Users\\username\\mcp-claude-spotify
• your_client_id_here con el Client ID que obtuviste de Spotify
• your_client_secret_here con el Client Secret que obtuviste de Spotify

Si ya tienes otros MCP configurados, simplemente añade la sección "spotify" dentro del objeto "mcpServers".

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

Para una experiencia más fiable, puedes configurar scripts de inicio automático:

@echo off
cd %~dp0
node build/index.js

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.spotify.mcp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/node</string>
        <string>ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardErrorPath</key>
    <string>/tmp/spotify-mcp.err</string>
    <key>StandardOutPath</key>
    <string>/tmp/spotify-mcp.out</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>SPOTIFY_CLIENT_ID</key>
        <string>your_client_id_here</string>
        <key>SPOTIFY_CLIENT_SECRET</key>
        <string>your_client_secret_here</string>
    </dict>
</dict>
</plist>

[Unit]
Description=Spotify MCP Server for Claude Desktop
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/node ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js
Restart=on-failure
Environment="SPOTIFY_CLIENT_ID=your_client_id_here"
Environment="SPOTIFY_CLIENT_SECRET=your_client_secret_here"

[Install]
WantedBy=default.target

systemctl --user enable spotify-mcp.service
systemctl --user start spotify-mcp.service

systemctl --user status spotify-mcp.service

Uso

1. Reinicia Claude Desktop después de modificar la configuración
2. En Claude, usa 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, reinicia Claude Desktop para inicializar correctamente el registro de herramientas del MCP y la caché de tokens de sesión de WebSocket
6. Después de reiniciar, todas las herramientas del MCP de Spotify estarán correctamente registradas y disponibles para su uso

El servidor MCP se ejecuta como un proceso hijo gestionado por Claude Desktop. Cuando Claude está en ejecución, inicia y gestiona automáticamente el proceso del servidor Node.js según la configuración en claude_desktop_config.json.

Herramientas disponibles

Autenticación

auth-spotify

Inicia el proceso de autenticación de Spotify.

Búsqueda

search-spotify

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

Parámetros:

• query: Texto de búsqueda
• type: Tipo de búsqueda (track, album, artist, playlist)
• limit: Número de resultados (1-10, predeterminado: 5)

Control de reproducción

get-current-playback

Obtiene información sobre el estado actual de la reproducción.

play-track

Reproduce una canción específica en un dispositivo activo.

Parámetros:

• trackId: ID de la canción en Spotify
• deviceId: (Opcional) ID del dispositivo de Spotify en el que reproducir

pause-playback

Pausa la reproducción actual.

next-track

Salta a la siguiente canción.

previous-track

Vuelve a la canción anterior.

Gestión de listas de reproducción

get-user-playlists

Obtiene una lista de las listas de reproducción del usuario.

Parámetros:

• limit: (Opcional) Número de listas de reproducción a devolver (1-50, predeterminado: 20)
• offset: (Opcional) Índice de la primera lista de reproducción a devolver (predeterminado: 0)

create-playlist

Crea una nueva lista de reproducción para el usuario actual.

Parámetros:

• name: Nombre de la lista de reproducción
• description: (Opcional) Descripción
• public: (Opcional) Si es pública o privada

update-playlist

Actualiza el nombre, la descripción, el estado público/privado o la configuración colaborativa de una lista de reproducción.

Parámetros:

• playlistId: ID de la lista de reproducción en Spotify
• name: (Opcional) Nuevo nombre para la lista de reproducción
• description: (Opcional) Nueva descripción para la lista de reproducción
• public: (Opcional) Si la lista de reproducción debe ser pública
• collaborative: (Opcional) Si la lista de reproducción debe ser colaborativa (primero debe establecerse como pública en falso)

delete-playlist

Deja de seguir (elimina) una lista de reproducción de tu biblioteca. La lista de reproducción sigue existiendo en Spotify pero ya no está en tu biblioteca.

Parámetros:

• playlistId: ID de la lista de reproducción en Spotify

get-playlist-tracks

Obtiene las canciones de una lista de reproducción con soporte de paginación.

Parámetros:

• playlistId: ID de la lista de reproducción en Spotify
• limit: (Opcional) Número de canciones a devolver (1-50, predeterminado: 20)
• offset: (Opcional) Índice de la primera canción a devolver (predeterminado: 0)

add-tracks-to-playlist

Añade canciones a una lista de reproducción.

Parámetros:

• playlistId: ID de la lista de reproducción
• trackIds: Matriz de IDs de canciones

remove-tracks-from-playlist

Elimina canciones de una lista de reproducción.

Parámetros:

• playlistId: ID de la lista de reproducción en Spotify
• trackIds: Matriz de IDs de canciones de Spotify a eliminar

reorder-playlist-tracks

Reordena canciones en una lista de reproducción moviendo un rango de canciones a una nueva posición.

Parámetros:

• playlistId: ID de la lista de reproducción en Spotify
• rangeStart: Posición de la primera canción a mover
• insertBefore: Posición donde deben insertarse las canciones
• rangeLength: (Opcional) Número de canciones a mover (predeterminado: 1)

get-playlist-cover

Obtiene la imagen de portada de una lista de reproducción.

Parámetros:

• playlistId: ID de la lista de reproducción en Spotify

upload-playlist-cover

Sube una imagen de portada personalizada para una lista de reproducción (JPEG codificado en base64, máximo 256KB).

Parámetros:

• playlistId: ID de la lista de reproducción en Spotify
• imageBase64: Imagen JPEG codificada en base64

Descubrimiento e historial

get-recommendations

Obtiene recomendaciones de canciones basadas en canciones, artistas o géneros semilla.

Parámetros:

• seedTracks: (Opcional) Matriz de IDs de canciones de Spotify
• seedArtists: (Opcional) Matriz de IDs de artistas de Spotify
• seedGenres: (Opcional) Matriz de nombres de géneros
• limit: (Opcional) Número de recomendaciones (1-100, predeterminado: 20)

get-top-tracks

Obtiene las canciones más reproducidas del usuario en un rango de tiempo especificado.

Parámetros:

• limit: (Opcional) Número de canciones a devolver (1-50, predeterminado: 20)
• offset: (Opcional) Índice de la primera canción a devolver (predeterminado: 0)
• time_range: (Opcional) Período 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

get-recently-played

Obtiene las canciones reproducidas recientemente por el usuario.

Parámetros:

• limit: (Opcional) Número máximo de canciones a devolver (1-50, predeterminado: 20)
• before: (Opcional) Marca de tiempo Unix en milisegundos. Devuelve canciones reproducidas antes de este momento
• after: (Opcional) Marca de tiempo Unix en milisegundos. Devuelve canciones reproducidas después de este momento

Solución de problemas

Error de "Servidor desconectado"

Si ves el error "MCP Spotify: Server disconnected" en Claude Desktop:

1. Verifica que el servidor esté en ejecución:

   • Abre una terminal y ejecuta manualmente node build/index.js desde el directorio del proyecto
   • Si el servidor se inicia correctamente, usa Claude mientras mantienes esta terminal abierta

2. Comprueba tu configuración:

   • Asegúrate de que la ruta absoluta en claude_desktop_config.json sea correcta para tu sistema
   • Verifica que hayas usado dobles barras invertidas (\\) para rutas de Windows
   • Confirma que estás usando la ruta completa desde la raíz de tu sistema de archivos

3. Prueba la opción de inicio automático:

   • Configura el script de inicio automático para tu sistema operativo como se describe en la sección "Configuración de scripts de inicio automático"
   • Esto garantiza que el servidor esté siempre en ejecución cuando lo necesites

El navegador no se abre automáticamente

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

Error de autenticación

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

Error de inicio del servidor

Verifica que:

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

Las herramientas no aparecen en Claude

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

• Asegúrate de haber reiniciado Claude Desktop después de una autenticación exitosa
• Revisa los registros de Claude Desktop para ver si hay errores de comunicación del MCP
• Asegúrate de que el proceso del servidor MCP esté en ejecución (ejecútalo manualmente para confirmarlo)
• Verifica que el servidor MCP esté correctamente registrado en el registro de MCP de Claude Desktop

Comprobando si el servidor está en ejecución

Para comprobar si el servidor está en ejecución:

• 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 use el método de inicio automático.

Pruebas

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

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

Ejecutar pruebas

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

npm install

Para ejecutar todas las pruebas:

npm test

Para ejecutar un archivo de prueba específico:

npm test -- --testMatch="**/tests/schemas.test.ts"

Si encuentra problemas con los módulos ESM, asegúrese de usar Node.js v16 o superior y de que la variable de entorno NODE_OPTIONS incluya la bandera --experimental-vm-modules según lo configurado en package.json.

Estructura de pruebas

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

Añadir nuevas pruebas

Al añadir nueva funcionalidad, incluya las pruebas correspondientes:

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

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

Notas de seguridad

• Nunca comparta su ID de cliente y 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 de la aplicación

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

• Ya no use esta integración.
• Sospeche de acceso no autorizado.
• Esté solucionando problemas de autenticación.

Para revocar el acceso:

1. Vaya a su página de cuenta de Spotify
2. Navegue a "Apps" en el menú.
3. Encuentre "MCP Claude Spotify" (o el nombre que eligió para su aplicación).
4. Haga clic en "QUITAR ACCESO".

Esto invalida inmediatamente todos los tokens de acceso y actualización. La próxima vez que use el comando auth-spotify, deberá autorizar la aplicación nuevamente.

Contribuciones

¡Las contribuciones son bienvenidas! Aquí hay algunas pautas a seguir:

Flujo de trabajo de desarrollo

1. Haga un fork del repositorio.
2. Cree una rama de características (git checkout -b feature/amazing-feature).
3. Realice sus cambios.
4. Ejecute las pruebas para asegurarse de que pasen (npm test).
5. Confirme sus cambios (git commit -m 'Add some amazing feature').
6. Envíe a la rama (git push origin feature/amazing-feature).
7. Abra una solicitud de extracción.

Pautas de estilo de código

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

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

Estructura del proyecto

El proyecto sigue esta estructura:

mcp-claude-spotify/
├── src/               # Source code
├── build/             # Compiled JavaScript
├── tests/             # Test files
├── public/            # Public assets
└── ...

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. Añada pruebas para la nueva funcionalidad.
4. Asegúrese de que todas las pruebas pasen.
5. Su PR será revisado por los mantenedores.

Enlaces relacionados

• Protocolo de Contexto de Modelo
• Documentación de la API Web de Spotify
• Claude Desktop
• Serie MCP

Licencia

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