Vulpes Spotify

Interactúa con Spotify para buscar y reproducir canciones usando un asistente de IA.

Documentación

Vulpes Spotify MCP Server

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

Características

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

Requisitos

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

Instalación

Instalación mediante Smithery

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

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

Instalación manual

Clona este repositorio:

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

Instala las dependencias:
```
npm install
```

Crea un archivo .env con tus credenciales de la 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

Puedes obtener tu ID de cliente y secreto desde el Panel de desarrollador de Spotify.

Genera un token de actualización (requerido para el control de reproducción):

Hay dos formas de obtener un token de actualización:

Opción 1: Usar el script integrado
```
npm run get-token
```
Esto iniciará un servidor local y proporcionará instrucciones en la terminal.

Opción 2: Usar 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. Después de autorizar, 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 requeridos (ya incluidos en los scripts):
- user-read-playback-state
- user-modify-playback-state
- user-read-currently-playing
- playlist-read-private
- playlist-read-collaborative
Añade el token de actualización a tu archivo .env:
```
SPOTIFY_REFRESH_TOKEN=your_refresh_token
```
Compila el proyecto:
```
npm run build
```

Uso con Claude Desktop

Primero, asegúrate de que Spotify esté abierto y reproduciendo en tu dispositivo

Añade este servidor a tu configuración de Claude Desktop:

Edita tu 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.

Reinicia Claude Desktop
Ahora deberías ver las herramientas de Spotify disponibles al hacer clic en el icono de martillo en Claude Desktop

Herramientas disponibles

spotify-search: Buscar pistas por consulta
spotify-play: Reproducir una pista específica por ID o URI
spotify-currently-playing: Obtener información sobre la pista que se está reproduciendo actualmente
spotify-devices: Listar los dispositivos de reproducción de Spotify disponibles
spotify-search-and-play: Buscar una pista y reproducir automáticamente el mejor resultado
spotify-playlists: Obtener 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: Reproducir una lista de reproducción específica (con opción de aleatorio)
spotify-find-playlist: Encontrar una lista de reproducción por nombre y reproducirla (recomendado para uso con IA)

Solución de problemas

"No se encontró ningún dispositivo activo": Asegúrate de que Spotify esté abierto y reproduciendo en al menos uno de tus dispositivos
"Permisos faltantes": Tu token de actualización puede no tener los ámbitos requeridos
"No es premium": El control de reproducción requiere una cuenta de Spotify Premium
"Problemas con el token de actualización": Si tu token expira, genera uno nuevo usando los pasos de la sección de instalación

Notas importantes

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

Licencia

MIT