Spotify

Conecta tu cuenta de Spotify con herramientas de IA, permitiendo el acceso a tu biblioteca musical, listas de reproducción y controles de reproducción.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de Spotify

Conecta tu cuenta de Spotify a herramientas de IA y automatiza tu experiencia musical con el Protocolo de Contexto de Modelos (MCP).

El Servidor MCP de Spotify implementa el Protocolo de Contexto de Modelos para conectar tu cuenta de Spotify con herramientas impulsadas por IA como Cursor, Claude, VS Code y más. Permite que los modelos de IA busquen, analicen y gestionen tu biblioteca musical de Spotify, listas de reproducción y reproducción mediante instrucciones en lenguaje natural.

✨ Características Principales

🎵 Búsqueda y Descubrimiento de Música: Encuentra canciones, álbumes, artistas, listas de reproducción, programas y episodios
📝 Gestión de Listas de Reproducción: Ver, crear, actualizar, reordenar y gestionar listas de reproducción
📚 Acceso a la Biblioteca del Usuario: Accede y modifica tus canciones, álbumes y programas guardados
🎯 Recomendaciones Personalizadas: Obtén sugerencias musicales basadas en tus gustos
📊 Análisis de Audio: Recupera características de audio (bailabilidad, energía, tempo, etc.) de las canciones
🎧 Control de Reproducción: (Solo Premium) Reproducir, pausar, saltar y controlar dispositivos de reproducción
📈 Información del Usuario: Ve tus canciones, artistas y historial de escucha más populares
🔄 Gestión de Cola: Añade canciones a tu cola y ve las próximas canciones
📱 Gestión de Dispositivos: Transfiere la reproducción entre dispositivos

🚀 Guía de Inicio Rápido

Requisitos Previos

Una cuenta de Spotify (se requiere Premium para el control de reproducción)
Credenciales de la API de Spotify (ver más abajo)
Node.js 18 o superior

Paso 1: Obtén las Credenciales de la API de Spotify

Ve al Panel de Desarrolladores de Spotify
Crea una nueva aplicación
Anota tu ID de Cliente y Secreto de Cliente
Establece la URI de Redirección a: http://127.0.0.1:8000/callback

Paso 2: Configura las Variables de Entorno

Crea un archivo .env en la raíz de tu proyecto:

SPOTIFY_CLIENT_ID=your-client-id
SPOTIFY_CLIENT_SECRET=your-client-secret
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8000/callback

Nota: ¡Ya no necesitas obtener tokens de acceso manualmente! El servidor gestionará el flujo OAuth automáticamente.

Paso 3: Instala y Ejecuta

# Install dependencies
npm install

# Build the server
npm run build

# Start the server
npm start

Paso 4: Conéctate desde tu Herramienta de IA

Añade esta configuración a tu aplicación compatible con MCP (ejemplo para Cursor):

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@tdp2003/spotify-mcp@latest"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your-client-id",
        "SPOTIFY_CLIENT_SECRET": "your-client-secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8000/callback"
      }
    }
  }
}

Paso 5: Completa la Autorización

Llama a la herramienta get_initial_context en tu aplicación de IA
Si aún no estás autorizado, recibirás una URL de autorización
Abre la URL en tu navegador e inicia sesión en Spotify
Autoriza la aplicación: serás redirigido automáticamente
Llama a get_initial_context nuevamente para confirmar la conexión

🛠️ Herramientas Disponibles

⚠️ Importante: Siempre llama a get_initial_context primero para inicializar tu conexión de Spotify antes de usar cualquier otra herramienta.

🔧 Contexto y Configuración

`get_initial_context`

Primer paso requerido - Inicializa tu conexión de Spotify y proporciona instrucciones de uso. Esta herramienta debe llamarse antes de cualquier otra operación.

Qué hace:

Valida tus credenciales de la API de Spotify
Inicia el flujo OAuth si es necesario
Recupera tu perfil de usuario e información de la cuenta
Proporciona estado de conexión y funciones disponibles
Devuelve instrucciones de uso para el asistente de IA

📝 Operaciones con Listas de Reproducción

`get_user_playlists`

Recupera listas de reproducción del usuario actual o de un usuario específico.

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)
userId (opcional): ID de usuario para obtener listas de reproducción (predeterminado: usuario actual)

Devuelve: Metadatos de la lista de reproducción, incluidos nombre, descripción, número de canciones, configuración de privacidad e información del propietario.

`create_playlist`

Crea una nueva lista de reproducción con configuraciones personalizables.

Parámetros:

name (requerido): Nombre de la lista de reproducción
description (opcional): Descripción de la lista de reproducción
public (opcional): Si la lista de reproducción es pública (predeterminado: false)
collaborative (opcional): Si la lista de reproducción es colaborativa (predeterminado: false)
userId (opcional): ID de usuario para crear la lista de reproducción (predeterminado: usuario actual)

Devuelve: Detalles de la lista de reproducción creada, incluidos URI e ID de Spotify.

`update_playlist_details`

Actualiza los metadatos de la lista de reproducción, incluidos nombre, descripción, configuración de privacidad y estado colaborativo.

Parámetros:

playlistId (requerido): ID de la lista de reproducción de Spotify
name (opcional): Nuevo nombre de la lista de reproducción
description (opcional): Nueva descripción de la lista de reproducción
public (opcional): Nueva configuración pública/privada
collaborative (opcional): Nueva configuración colaborativa

Devuelve: Detalles actualizados de la lista de reproducción con resumen de cambios.

`add_tracks_to_playlist`

Añade canciones a una lista de reproducción con control preciso de posición.

Parámetros:

playlistId (requerido): ID de la lista de reproducción de Spotify
uris (requerido): Matriz de URIs de canciones de Spotify (máx. 100)
position (opcional): Posición para insertar canciones (predeterminado: al final)

Devuelve: Confirmación con ID de instantánea y número actualizado de canciones.

`remove_tracks_from_playlist`

Elimina canciones de una lista de reproducción con control de precisión.

Parámetros:

playlistId (requerido): ID de la lista de reproducción de Spotify
tracks (requerido): Matriz de objetos de canción con URIs y posiciones opcionales
snapshot_id (opcional): ID de instantánea de la lista de reproducción para seguridad de concurrencia

Devuelve: Confirmación con ID de instantánea y detalles de eliminación.

`reorder_playlist_tracks`

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

Parámetros:

playlistId (requerido): ID de la lista de reproducción de Spotify
range_start (requerido): Posición inicial de las canciones a mover
range_length (requerido): Número de canciones a mover
insert_before (requerido): Posición a la que mover las canciones
snapshot_id (opcional): ID de instantánea de la lista de reproducción para seguridad de concurrencia

Devuelve: Confirmación con ID de instantánea y detalles de reordenamiento.

🔍 Búsqueda y Descubrimiento de Música

`search`

Busca en el catálogo de Spotify álbumes, artistas, canciones, listas de reproducción, programas y episodios.

Parámetros:

query (requerido): Cadena de consulta de búsqueda
type (opcional): Filtro de tipo de contenido (track, album, artist, playlist, show, episode)
limit (opcional): Número de resultados (1-50, predeterminado: 20)
offset (opcional): Desplazamiento de resultados (predeterminado: 0)
market (opcional): Código de país para resultados específicos del mercado

Devuelve: Metadatos detallados para cada tipo de resultado con información de paginación.

`get_new_releases`

Obtén nuevos lanzamientos de álbumes disponibles en Spotify.

Parámetros:

limit (opcional): Número de lanzamientos (1-50, predeterminado: 20)
offset (opcional): Desplazamiento de resultados (predeterminado: 0)
country (opcional): Código de país para lanzamientos regionales

Devuelve: Álbumes lanzados recientemente con información del artista, fechas de lanzamiento y metadatos.

`get_featured_playlists`

Obtén listas de reproducción destacadas del equipo editorial de Spotify.

Parámetros:

limit (opcional): Número de listas de reproducción (1-50, predeterminado: 20)
offset (opcional): Desplazamiento de resultados (predeterminado: 0)
country (opcional): Código de país para contenido regional
locale (opcional): Idioma/localización para descripciones

Devuelve: Listas de reproducción seleccionadas destacadas en Spotify con descripciones y metadatos.

👤 Biblioteca e Información del Usuario

`get_user_top_items`

Obtén los artistas o canciones más populares del usuario actual según la afinidad calculada.

Parámetros:

type (requerido): Tipo de elemento ('artists' o 'tracks')
time_range (opcional): Rango de tiempo ('short_term' ~4 semanas, 'medium_term' ~6 meses, 'long_term' ~1 año)
limit (opcional): Número de elementos (1-50, predeterminado: 20)
offset (opcional): Desplazamiento de resultados (predeterminado: 0)

Devuelve: Elementos más populares del usuario con puntuaciones de popularidad y metadatos.

🎧 Control de Reproducción (Solo Premium)

Nota: Estas herramientas requieren una cuenta de Spotify Premium

`get_current_playback`

Obtén información sobre la canción y el dispositivo de reproducción actual.

Devuelve: Estado de reproducción actual, incluidos canción, dispositivo e información de la cola.

`playback_control`

Controla la reproducción (reproducir, pausar, saltar, volumen).

Parámetros:

action (requerido): Acción de reproducción (play, pause, next, previous, volume)
device_id (opcional): ID del dispositivo de destino
volume_percent (opcional): Nivel de volumen (0-100, para la acción de volumen)

Devuelve: Confirmación de la acción de reproducción.

`queue_management`

Añade canciones a la cola y ve las próximas canciones.

Parámetros:

action (requerido): Acción de cola ('add' o 'get')
uris (opcional): URIs de canciones a añadir (para la acción 'add')
device_id (opcional): ID del dispositivo de destino

Devuelve: Información de la cola o confirmación de adición de canciones.

`device_management`

Transfiere la reproducción entre dispositivos.

Parámetros:

device_id (requerido): ID del dispositivo de destino
play (opcional): Si iniciar la reproducción al transferir (predeterminado: false)

Devuelve: Confirmación de la transferencia de dispositivo.

📊 Análisis de Audio

`get_audio_features`

Recupera características de audio de las canciones.

Parámetros:

track_ids (requerido): Matriz de IDs de canciones de Spotify

Devuelve: Características de audio, incluyendo:

Bailabilidad: Qué tan adecuada para bailar (0.0-1.0)
Energía: Intensidad y potencia (0.0-1.0)
Habla: Presencia de palabras habladas (0.0-1.0)
Acústica: Si la canción es acústica (0.0-1.0)
Instrumentalidad: Si la canción no tiene voces (0.0-1.0)
En vivo: Presencia de audiencia (0.0-1.0)
Valencia: Positividad/felicidad musical (0.0-1.0)
Tempo: Velocidad en pulsos por minuto (BPM)

⚙️ Variables de Entorno

Variable	Descripción	Requerida
SPOTIFY_CLIENT_ID	ID de cliente de Spotify	✅
SPOTIFY_CLIENT_SECRET	Secreto de cliente de Spotify	✅
SPOTIFY_REDIRECT_URI	URI de redirección de Spotify (usa http://127.0.0.1:8000/callback)	✅
SPOTIFY_API_TOKEN	Token de acceso de Spotify (obtenido vía OAuth)	❌*
SPOTIFY_REFRESH_TOKEN	Token de actualización de Spotify (obtenido vía OAuth)	❌*
MAX_TOOL_TOKEN_OUTPUT	Salida máxima de tokens para respuestas de herramientas (predeterminado 50000)	❌

*Estos tokens se obtienen automáticamente mediante el flujo OAuth cuando usas el servidor por primera vez.

👥 Roles de Usuario

developer: Acceso completo a todas las herramientas y funciones
editor: Restringido a herramientas centradas en contenido (sin funciones de administración)

Configura el rol en la configuración de tu cliente MCP si es compatible.

📦 Configuración del Entorno Node.js

Si usas un gestor de versiones de Node (nvm, mise, fnm, etc.), es posible que necesites crear enlaces simbólicos para que los servidores MCP puedan acceder a Node.js:

sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx

Actualiza estos enlaces simbólicos si cambias las versiones de Node. Elimínalos con:

sudo rm /usr/local/bin/node /usr/local/bin/npx

💻 Desarrollo

Instala las dependencias:

npm install

Compila y ejecuta en modo de desarrollo:

npm run dev

Compila el servidor:

npm run build

Ejecuta el servidor compilado:

npm start

🧑‍💻 Depuración

Puedes usar el inspector de MCP para depurar:

npx @modelcontextprotocol/inspector -e SPOTIFY_CLIENT_ID=... -e SPOTIFY_CLIENT_SECRET=... -e SPOTIFY_REDIRECT_URI=... -e SPOTIFY_API_TOKEN=... -e SPOTIFY_REFRESH_TOKEN=... node path/to/build/index.js

Esto proporciona una interfaz web para inspeccionar y probar las herramientas disponibles.

Flujo OAuth

El flujo OAuth se ha mejorado con las siguientes mejoras de seguridad y usabilidad:

Mejoras de Seguridad

Validación de estado: Usa parámetros de estado aleatorios criptográficamente seguros para prevenir ataques CSRF
Validación de URI de redirección: Asegura que la URI de redirección use localhost/127.0.0.1 para el intercambio automático de tokens
Manejo adecuado de errores: Manejo integral de errores para todos los escenarios de fallo de OAuth

Mejoras de Usabilidad

Apertura automática del navegador: Abre automáticamente la URL de autorización en tu navegador predeterminado
Mejor retroalimentación al usuario: Mensajes de error claros y actualizaciones de estado durante todo el proceso
Apagado elegante del servidor: Cierra correctamente el servidor de devolución de llamada OAuth después de completarse

Uso del Asistente OAuth

El script oauth-helper.js proporciona una forma independiente de obtener tokens de Spotify:

node src/utils/oauth-helper.js

Esto hará:

Validar la configuración de tu entorno
Iniciar un servidor de devolución de llamada local
Abrir automáticamente tu navegador en la página de autorización de Spotify
Manejar la devolución de llamada e intercambiar el código por tokens
Mostrar los tokens para que los agregues a tu archivo .env

Variables de Entorno

Asegúrate de que tu URI de redirección esté configurada correctamente:

SPOTIFY_REDIRECT_URI=http://127.0.0.1:8000/callback

La URI de redirección debe usar localhost o 127.0.0.1 para que el intercambio automático de tokens funcione correctamente.

Licencia

MIT