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

⚙️ 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

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.

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:

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:

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:

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:

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:

🌐 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

• 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