Servidor MCP de Spotify

Un servidor basado en Node.js que se integra con la API web de Spotify y el Protocolo de Contexto de Modelo (MCP) para proporcionar herramientas de búsqueda, control de reproducción y gestión de contenido de Spotify. Permite a los usuarios interactuar con su cuenta de Spotify mediante programación a través de una interfaz MCP estandarizada sobre el transporte stdio.

🧠 Descripción general del proyecto

Nombre: Servidor MCP de Spotify
Descripción: Una interfaz programable que conecta Spotify Web API con el estándar MCP, lo que permite la búsqueda, el control de reproducción y la gestión de listas de reproducción mediante herramientas basadas en JSON sobre stdio.
Características principales:

• 🔍Busca pistas en Spotify

• 🎵 Verificar el estado actual de la reproducción

• ▶️ Reproducir pistas específicas por URI

• 📋 Recuperar listas de reproducción de usuarios

• ⏸ Pausar la reproducción en curso

• 🔐 Autenticación OAuth con Spotify

• 📉 Manejo de límites de velocidad para solicitudes de API de Spotify

Related MCP server: MCP Spotify Player

⚙️ Requisitos previos

• Node.js (se recomienda v16 o superior)

• Una cuenta de desarrollador de Spotify con credenciales de la aplicación

• npm (Administrador de paquetes de Node)

📦 Pasos de instalación

# 1. Clone the repository
git clone <repository-url>
cd spotify-mcp

# 2. Install dependencies
npm install

# 3. Create a .env file and add the following:

SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback

Nota: Reemplaza your_spotify_client_id y your_spotify_client_secret con las credenciales de tu aplicación Spotify Developer. La URI de redirección debe coincidir con la configurada en la configuración de tu aplicación Spotify.

# 4. Build
npm run build
# 5. Run the server
npm start

Esto abrirá un navegador para la autenticación de Spotify e iniciará el servidor usando el transporte stdio.

🔧 Herramientas

1. search_tracks

• Descripción: Busca pistas en Spotify según una cadena de consulta.

• Esquema de entrada:

  • query (cadena, obligatoria): término de búsqueda (por ejemplo, nombre del artista, título de la canción).

• Salida: matriz JSON de hasta 5 objetos de pista con name , artist , album , release_date , popularity , id y uri .

• Ejemplo:

{
  "name": "search_tracks",
  "arguments": {"query": "The Beatles"}
}

2. get_playback_state

• Descripción: Recupera el estado de reproducción actual de la cuenta de Spotify del usuario.

• Esquema de entrada: Ninguno

• Salida: objeto JSON con información de la pista actual, estado de reproducción y detalles del dispositivo, o "Sin reproducción activa" si no se está reproduciendo nada.

• Ejemplo:

{
  "name": "get_playback_state",
  "arguments": {}
}

3. play_track

• Descripción: Reproduce una pista específica utilizando su URI de Spotify.

• Esquema de entrada:

  • uri (cadena, obligatoria): URI de la pista de Spotify (por ejemplo, spotify:track:xxx ).

• Salida: Confirmación JSON con status y uri .

• Ejemplo:

{
  "name": "play_track",
  "arguments": {"uri": "spotify:track:7KXjTSCq5nL1LoYtL7XAwS"}
}

4. get_user_playlists

• Descripción: Obtiene las listas de reproducción del usuario de Spotify.

• Esquema de entrada:

  • limit (número, opcional): número máximo de listas de reproducción a devolver (predeterminado: 20).

• Salida: matriz JSON de objetos de lista de reproducción con name , id , track_count , uri y estado public .

• Ejemplo:

{
  "name": "get_user_playlists",
  "arguments": {"limit": 10}
}

5. pause_playback

• Descripción: Pausa la reproducción actual en el dispositivo Spotify activo del usuario.

• Esquema de entrada: Ninguno

• Salida: Confirmación JSON con estado "Reproducción en pausa".

• Ejemplo:

{
  "name": "pause_playback",
  "arguments": {}
}

🌐 Casos de uso

1. Bot de descubrimiento de música:

   • Utilice search_tracks y play_track para implementar chatbots de música basados en el estado de ánimo.

2. Herramienta de gestión de listas de reproducción:

   • Utilice get_user_playlists y search_tracks para obtener una vista previa y organizar las listas de reproducción.

3. Automatización del control de reproducción:

   • Automatice las acciones de reproducción utilizando get_playback_state , play_track y pause_playback .

4. Panel de control de Spotify:

   • Cree un widget de escritorio usando get_playback_state , get_user_playlists , pause_playback y play_track .

5. Aprendiendo la API de Spotify:

   • Experimente con todas las herramientas para aprender cómo funciona la API web de Spotify.

🔐 Detalles de autenticación

• En la primera ejecución, el servidor abre un navegador para la autenticación OAuth de Spotify.

• Recibe código a través de http://localhost:8888/callback .

• Intercambia el código por tokens de acceso y actualización.

• Actualiza automáticamente los tokens dentro de los 5 minutos posteriores a su vencimiento.

⏱ Limitación de velocidad

• Maneja los límites de velocidad de la API de Spotify con estrategias de reintento:

  • Tiempo de recuperación de 10 segundos después de cada solicitud.

  • 1 minuto de espera si se produce el error 429 Demasiadas solicitudes.

📊 Dependencias

npm install dotenv spotify-web-api-node @modelcontextprotocol/sdk open

• dotenv : carga variables de entorno desde .env .

• spotify-web-api-node : cliente de API de Spotify.

• @modelcontextprotocol/sdk : Implementa el servidor MCP.

• http , url : elementos integrados de Node.js para el servidor de redireccionamiento OAuth.

• open : abre el navegador predeterminado para la autenticación.

📁 Información de desarrollo

• Punto de entrada: index.js

• Lenguaje: JavaScript (Node.js con módulos ES)

• Ejecutar comando: node index.js

• Depuración: verifique los registros de la consola para detectar errores de MCP o autenticación.

⚠️ Limitaciones

• Se requiere Spotify Premium para controlar la reproducción.

• Solo admite transporte stdio (no HTTP, WebSocket, etc.).

• search_tracks devuelve un máximo de 5 resultados.

• Asume un único dispositivo activo para la reproducción.

🚀 Contribuyendo

No dudes en abrir problemas o enviar solicitudes de extracción a:

• Añadir nuevas herramientas

• Mejorar la funcionalidad existente

• Mejorar la documentación

✍️ Licencia

Licencia MIT: libre para usar, modificar y distribuir para uso personal o comercial.

❤️ Pie de página

Creado con ❤️ por Rakshitha C Devadiga el 17 de marzo de 2025