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).

Eliminado en 0.6.0 — get-recommendations. Spotify dejó de admitir /v1/recommendations el 27 de noviembre de 2024, junto con artistas-relacionados, características-de-audio, análisis-de-audio, listas-de-reproducción-destacadas y URL de vista previa de 30 segundos. Las aplicaciones creadas después de esa fecha reciben 403 Forbidden, y las aplicaciones aún en modo de desarrollo también perdieron el acceso, por lo que la herramienta no podía funcionar para prácticamente nadie. Usa search-spotify y get-top-tracks en su lugar. Consulta el anuncio de Spotify.

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)
• Lee tus canciones más escuchadas y tu historial de reproducción
• Accede a las canciones más reproducidas del usuario en diferentes períodos de tiempo
• Consulta las canciones reproducidas recientemente

Demostración

Requisitos

• Node.js 20 o superior
• Cuenta de Spotify
• Claude Desktop
• Credenciales de la API de Spotify (ID de cliente y Secreto de cliente)

Instalación

Instalación mediante Smithery

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

npx -y @smithery/cli@latest mcp add 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 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 "Crear aplicación"
4. Completa la información de tu aplicación:
   • Nombre de la aplicación: "MCP Claude Spotify" (o lo que prefieras)
   • Descripción de la aplicación: "Integración de Spotify para Claude Desktop"
   • Sitio web: Puedes dejarlo en blanco o poner cualquier URL
   • URI de redirección: Importante - Agrega http://127.0.0.1:8888/callback
5. Acepta los términos y condiciones y haz clic en "Crear"
6. En el panel de tu aplicación, verás el "ID de cliente"
7. Haz clic en "Mostrar secreto de cliente" para revelar tu "Secreto de cliente"

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: Autorizar una vez desde una terminal (configuración inicial)

Claude Desktop inicia su propia copia del servidor, por lo que un servidor que se ejecute en una terminal no es el que Claude utiliza. Lo que sirve una ejecución en terminal es para autorizar una vez: con SPOTIFY_AUTO_AUTH=true y sin tokens almacenados, el servidor abre el inicio de sesión de Spotify en tu navegador tan pronto como se inicia.

SPOTIFY_CLIENT_ID=your_client_id \
SPOTIFY_CLIENT_SECRET=your_client_secret \
SPOTIFY_AUTO_AUTH=true \
node build/index.js

Aprueba la solicitud en el navegador. Una vez que la terminal muestre "Autorización completada", detén el proceso con Ctrl+C. El token se guarda en ~/.spotify-mcp/tokens.json, y la copia que inicia Claude Desktop lo tomará.

Puedes omitir este paso por completo y pedirle a Claude que "autentique con Spotify" en su lugar, lo cual ejecuta la herramienta auth-spotify y abre la misma página de inicio de sesión.

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

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 agregar 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 ID de cliente que obtuviste de Spotify
• your_client_secret_here con el Secreto de cliente que obtuviste de Spotify

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

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

Para una experiencia más confiable, 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

Desarrollo

npm install
npm run build
npm test

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.

Notas de seguridad

• La autorización está protegida contra CSRF. La URL de inicio de sesión lleva un valor state aleatorio que la devolución de llamada verifica antes de intercambiar un código. Las versiones anteriores a 0.6.0 no enviaban state, por lo que cualquier página abierta en tu navegador podía acceder a la devolución de llamada de bucle local y vincular una cuenta de Spotify diferente.
• El archivo de token es solo para el propietario. ~/.spotify-mcp/tokens.json contiene un token de actualización de larga duración y ahora se escribe con modo 600 en un directorio 700. Anteriormente se creaba con el modo predeterminado, dejándolo legible para todas las cuentas de la máquina.
• No se mata ningún proceso para liberar el puerto. Si el puerto 8888 está ocupado, el servidor lo informa y se detiene. Las versiones anteriores ejecutaban lsof -i:8888 -t | xargs kill -9 (y un equivalente de taskkill en Windows), matando con SIGKILL cualquier proceso no relacionado que ocupara ese puerto de desarrollo tan común.
• Los ID en los argumentos de las herramientas se validan. Los ID de canciones, listas de reproducción y dispositivos van en rutas de API y cadenas de consulta, por lo que solo se aceptan ID de Spotify simples; cualquier otra cosa se rechaza antes de que se construya una solicitud.
• La devolución de llamada escucha solo en bucle local (127.0.0.1). El listener express anterior se vinculaba a todas las interfaces de red, por lo que cualquier persona en la misma red podía acceder a /login y /callback. Los contenedores pueden ampliarlo con AUTH_BIND_HOST=0.0.0.0.
• El servidor de devolución de llamada se apaga una vez que se completa la autorización, en lugar de permanecer vinculado durante el resto de la sesión.

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 (canción, álbum, artista, lista de reproducción)
• limit: Número de resultados (1-10, predeterminado: 5)

Control de reproducción

get-current-playback

Obtiene información sobre el estado actual de 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 Spotify de la lista de reproducción
• 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 pública en falso)

delete-playlist

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

Parámetros:

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

get-playlist-tracks

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

Parámetros:

• playlistId: ID de Spotify de la lista de reproducción
• 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

Agrega canciones a una lista de reproducción.

Parámetros:

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

remove-tracks-from-playlist

Elimina canciones de una lista de reproducción.

Parámetros:

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

reorder-playlist-tracks

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

Parámetros:

• playlistId: ID de Spotify de la lista de reproducción
• rangeStart: Posición de la primera canción a mover
• insertBefore: Posición donde se deben insertar 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 Spotify de la lista de reproducción

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 Spotify de la lista de reproducción
• imageBase64: Imagen JPEG codificada en base64

Descubrimiento e historial

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) Marco 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 pistas a devolver (1-50, predeterminado: 20)
• before: (Opcional) Marca de tiempo Unix en milisegundos. Devuelve pistas reproducidas antes de este momento
• after: (Opcional) Marca de tiempo Unix en milisegundos. Devuelve pistas reproducidas después de este momento

Solución de problemas

Error "Servidor desconectado"

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

1. Verifica que el servidor esté ejecutándose:

   • 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. Revisa 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 asegura que el servidor esté siempre ejecutándose 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 al iniciar el 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 MCP
• Asegúrate de que el proceso del servidor MCP esté ejecutándose (ejecútalo manualmente para confirmar)
• Verifica que el servidor MCP esté correctamente registrado en el registro MCP de Claude Desktop

Verificar si el servidor está ejecutándose

Para verificar si el servidor está ejecutándose:

• Windows: Abre el Administrador de tareas, ve a la pestaña "Detalles" y busca "node.exe"
• macOS/Linux: Abre la Terminal y ejecuta ps aux | grep node

Si no ves el servidor ejecutándose, inícialo manualmente o usa 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 ejecución adecuados de las herramientas

Ejecutar pruebas

Primero, asegúrate 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 encuentras problemas con los módulos ESM, asegúrate de usar Node.js v16 o superior y que la variable de entorno NODE_OPTIONS incluya el indicador --experimental-vm-modules como se configura 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

Agregar nuevas pruebas

Al agregar nueva funcionalidad, incluye las pruebas correspondientes:

1. Para nuevos esquemas, agrega pruebas de validación en schemas.test.ts
2. Para funciones de la API de Spotify, agrega pruebas en spotify-api.test.ts
3. Para herramientas MCP, agrega 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 compartas tu Client ID y Client Secret
• 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 desees revocar el acceso de la aplicación a tu cuenta de Spotify cuando:

• Ya no uses esta integración
• Sospeches de acceso no autorizado
• Estés solucionando problemas de autenticación

Para revocar el acceso:

1. Ve a tu página de cuenta de Spotify
2. Navega a "Apps" en el menú
3. Busca "MCP Claude Spotify" (o el nombre que elegiste para tu aplicación)
4. Haz clic en "REMOVE ACCESS"

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

Contribuciones

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

Flujo de trabajo de desarrollo

1. Haz un fork del repositorio
2. Crea una rama de características (git checkout -b feature/amazing-feature)
3. Realiza tus cambios
4. Ejecuta las pruebas para asegurarte de que pasen (npm test)
5. Haz commit de tus cambios (git commit -m 'Add some amazing feature')
6. Haz push a la rama (git push origin feature/amazing-feature)
7. Abre una solicitud de extracción (Pull Request)

Pautas de estilo de código

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

• Usa TypeScript con verificación estricta de tipos
• Sigue el formato de módulo ESM
• Usa 2 espacios para la indentación
• Usa camelCase para variables y funciones
• Usa PascalCase para clases e interfaces
• Documenta las funciones con comentarios JSDoc
• Mantén 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úrate de que tu código siga las pautas de estilo
2. Actualiza la documentación si es necesario
3. Agrega pruebas para la nueva funcionalidad
4. Asegúrate de que todas las pruebas pasen
5. Tu PR será revisado por los mantenedores

Enlaces relacionados

• Model Context Protocol
• Documentación de la API Web de Spotify
• Claude Desktop
• Serie MCP

Licencia

Este proyecto está licenciado bajo la Mozilla Public License 2.0 - consulta el archivo LICENSE para más detalles.