Servidor MCP de Spotify

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona herramientas para interactuar con la API web de Spotify. Permite a asistentes de IA como Claude buscar música, controlar la reproducción, gestionar listas de reproducción y más.

Características

• Búsqueda - Encuentra pistas, álbumes, artistas, listas de reproducción, programas, episodios y audiolibros

• Control de reproducción - Reproducir, pausar, saltar, buscar, volumen, aleatorio, repetir, gestión de cola

• Listas de reproducción - Crear, actualizar, añadir/eliminar/reordenar pistas

• Biblioteca - Ver y gestionar pistas, álbumes, programas, episodios y audiolibros guardados

• Explorar - Obtener detalles de álbumes, información de artistas, metadatos de pistas

• Podcasts y audiolibros - Explorar programas, episodios, audiolibros y capítulos

• Perfil de usuario - Ver perfil, artistas/pistas principales, artistas seguidos

• 44 herramientas que cubren los endpoints no obsoletos de la API web de Spotify

Requisitos previos

• uv — instalar con curl -LsSf https://astral.sh/uv/install.sh | sh

• Una cuenta de Spotify Developer

• Una aplicación de Spotify con Client ID y Client Secret

Obtención de tus credenciales de Spotify

1. Ve al Panel de desarrollador de Spotify

2. Haz clic en Create App

3. Rellena los detalles de la aplicación:

   • App name: Elige cualquier nombre (p. ej., "My MCP Server")

   • App description: Opcional

   • Redirect URI: http://127.0.0.1:8888/callback

   • Which API/SDKs are you planning to use?: Selecciona Web API

4. Haz clic en Save

5. En la página de tu aplicación, busca tu Client ID

6. Haz clic en Show client secret para revelar tu Client Secret

Importante: La URI de redirección debe coincidir exactamente con http://127.0.0.1:8888/callback (o lo que hayas configurado en SPOTIFY_REDIRECT_URI). No uses localhost, usa 127.0.0.1.

Instalación

Elige tu cliente a continuación. Todos los ejemplos usan uvx para obtener el servidor bajo demanda: sin clonar, sin instalación manual.

Claude Code

claude mcp add spotify \
  -e SPOTIFY_CLIENT_ID=your_client_id \
  -e SPOTIFY_CLIENT_SECRET=your_client_secret \
  -- uvx mcp-server-spotify

Otros clientes MCP

La mayoría de los clientes MCP configuran los servidores a través de un archivo JSON. Añade esta entrada a la configuración MCP de tu cliente:

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["mcp-server-spotify"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Ejecución desde una copia local

Para desarrollo, o si deseas ejecutar una copia modificada:

git clone https://github.com/llyfn/spotify-mcp.git
cd spotify-mcp && uv sync

Luego apunta tu cliente a la copia local en lugar de a uvx:

"command": "uv",
"args": ["--directory", "/absolute/path/to/spotify-mcp", "run", "mcp-server-spotify"]

Configuración

Autenticación

El servidor utiliza el flujo de Código de Autorización de Spotify:

1. En el primer uso, el servidor abre tu navegador en la página de inicio de sesión de Spotify

2. Spotify te pedirá que apruebes el acceso: el servidor solicita todos los alcances necesarios para el conjunto completo de herramientas (reproducción, biblioteca, listas de reproducción y datos de usuario)

3. Después de autorizar, Spotify redirige al servidor de devolución de llamada local

4. El servidor intercambia el código de autorización por tokens de acceso/actualización

5. Los tokens se almacenan de forma segura en ~/.spotify-mcp/credentials.json

6. Los tokens se actualizan automáticamente cuando caducan

Si se ejecuta en un entorno sin interfaz gráfica (SSH, Docker), la URL de autenticación se imprimirá en stderr: cópiala y pégala en un navegador manualmente.

Reautenticación

Para volver a autenticarte (p. ej., después de revocar el acceso), elimina las credenciales almacenadas:

rm ~/.spotify-mcp/credentials.json

Herramientas disponibles

Búsqueda

Álbumes

Artistas

Pistas

Listas de reproducción

Biblioteca

Reproductor

Programas y Podcasts

Audiolibros

Usuarios

Seguir a artistas/usuarios utiliza las mismas herramientas save_to_library / remove_from_library / check_saved_in_library: pasa una URI de artista o usuario.

Contribución

Consulta CONTRIBUTING.md para la configuración de desarrollo y las directrices.

Licencia

MIT: consulta LICENSE para más detalles.