MCP Spotify AI Assistant

Un asistente de IA que controla funciones de Spotify como reproducción, listas de reproducción y b

GitHub

Prueba este MCPPatrocinado

Documentación

MCP Spotify AI Assistant

Un servidor de Model Context Protocol (MCP) que permite a Claude controlar funciones de Spotify.

Contenido

Interacciones de ejemplo
Herramientas
- Operaciones de lectura
- Operaciones de escritura
Configuración
Integración con Claude Desktop

Interacciones de ejemplo

"¿Puedes añadir las 5 mejores canciones de Coldplay a mi playlist vibes?"
"¿Cuáles son mis canciones más escuchadas este último mes?"
"¿Puedes reproducir en modo aleatorio mis mejores canciones?"

Herramientas

Operaciones de lectura

searchSpotify
- Descripción: Buscar pistas, álbumes, artistas o playlists en Spotify
- Parámetros:
  - query (string): El término de búsqueda
  - type (string): Tipo de elemento a buscar (track, album, artist, playlist)
  - limit (number, optional): Número máximo de resultados a devolver (10-50)
- Devuelve: Lista de elementos coincidentes con sus IDs, nombres y detalles adicionales
- Ejemplo: searchSpotify("bohemian rhapsody", "track", 20)
getTopItems
- Descripción: Obtener los artistas o pistas principales del usuario actual según la afinidad calculada
- Parámetros:
  - type (string): El tipo de entidad a devolver. Valores válidos: artists o tracks
  - time_range (string, optional): Durante qué período de tiempo se calculan las afinidades. Long_term ~1 año de datos, medium_term son los últimos 6 meses, short_term son las últimas 4 semanas
  - limit (number, optional): El número máximo de elementos a devolver. Predeterminado: 20, mínimo: 1, máximo: 50
- Devuelve: Lista de elementos coincidentes con nombre, IDs y detalles adicionales
- Ejemplo: getTopItems("artists", "short_term", 5)
getMyPlaylists
- Descripción: Obtener una lista de las playlists creadas o seguidas por el usuario actual de Spotify
- Parámetros:
  - limit (number, optional): El número máximo de elementos a devolver. Predeterminado: 20, mínimo: 1, máximo: 50
- Devuelve: Lista de playlists coincidentes con nombre, IDs y detalles adicionales
- Ejemplo: getMyPlaylists(25)
getPlaylistItems
- Descripción: Obtener detalles completos de los elementos de una playlist propiedad de un usuario de Spotify
- Parámetros:
  - playlist_id (string): El ID de Spotify de la playlist
  - fields (string, optional): Una lista separada por comas de los campos a devolver
  - limit (number, optional): El número máximo de elementos a devolver. Predeterminado: 20, mínimo: 1, máximo: 50
- Devuelve: Lista de elementos de playlist coincidentes con nombre, IDs y detalles adicionales
- Ejemplo: getPlaylistItems("123")
getCurrentUserProfile
- Descripción: Obtener información detallada del perfil del usuario actual
- Parámetros: Ninguno
- Devuelve: Nombre visible del usuario, ID, correo electrónico y número de seguidores
- Ejemplo: getCurrentUserProfile()
getCurrentlyPlaying
- Descripción: Obtener detalles completos de los elementos de una playlist propiedad de un usuario de Spotify
- Parámetros: Ninguno
- Devuelve: Devuelve el nombre del elemento que se está reproduciendo actualmente y sus detalles asociados
- Ejemplo: getCurrentlyPlaying()
getRecentlyPlayedTracks
- Descripción: Obtener detalles completos de los elementos de una playlist propiedad de un usuario de Spotify
- Parámetros:
  - limit (number, optional): El número máximo de elementos a devolver. Predeterminado: 20, mínimo: 1, máximo: 50
- Devuelve: Lista de nombres de pistas reproducidas recientemente e información adicional
- Ejemplo: getRecentlyPlayedTracks(20)
getUserQueue
- Descripción: Obtener la lista de objetos que componen la cola del usuario
- Parámetros: Ninguno
- Devuelve: Los nombres de los elementos e información adicional en la cola
- Ejemplo: getUserQueue()

Operaciones de escritura

startPlayback
- Descripción: Iniciar una nueva reproducción en el dispositivo activo
- Parámetros:
  - device_id (string, optional): El ID del dispositivo al que se dirige este comando
  - context_uri (number, optional): URI de Spotify del contexto a reproducir. Los contextos válidos son álbumes, artistas y playlists
  - type (number, optional): El tipo a reproducir. Los tipos válidos son track, album, artist o playlist
  - id (number, optional): El ID de Spotify del elemento a reproducir
- Devuelve: Reproducción iniciada
- Ejemplo: startPlayback()
resumePlayback
- Descripción: Reanudar la reproducción en el dispositivo activo
- Parámetros:
  - device_id (string, optional): El ID del dispositivo al que se dirige este comando
- Devuelve: Reproducción reanudada
- Ejemplo: resumePlayback()
pausePlayback
- Descripción: Pausar la reproducción en el dispositivo activo
- Parámetros:
  - device_id (string, optional): El ID del dispositivo al que se dirige este comando
- Devuelve: Reproducción pausada
- Ejemplo: pausePlayback()
addQueue
- Descripción: Añadir un elemento para que se reproduzca a continuación en la cola de reproducción
- Parámetros:
  - uri (string): La URI del elemento a añadir a la cola. Debe ser una URI de pista o de episodio
  - device_id (string, optional): El ID del dispositivo al que se dirige este comando
- Devuelve: Añadido a la cola
- Ejemplo: addQueue("123uri")
togglePlaybackShuffle
- Descripción: Activar o desactivar la reproducción aleatoria para la reproducción del usuario
- Parámetros:
  - state (boolean): Verdadero: Activar la reproducción aleatoria del usuario. Falso: No activar la reproducción aleatoria del usuario
  - device_id (string, optional): El ID del dispositivo al que se dirige este comando
- Devuelve: Reproducción aleatoria cambiada
- Ejemplo: togglePlaybackShuffle(true)
createPlaylist
- Descripción: Crear una playlist para un usuario de Spotify
- Parámetros:
  - device_id (string): El ID de usuario de Spotify
  - name (string): El nombre de tu nueva playlist
  - public (boolean, optional): El estado público/privado de la playlist
  - description (string, optional): La descripción de la playlist
- Devuelve: Nueva playlist creada
- Ejemplo: createPlaylist("user123", "new playlist", true, "This is a new playlist")
addItemsToPlaylist
- Descripción: Añade uno o más elementos a la playlist de un usuario
- Parámetros:
  - playlist_id (string): El ID de Spotify de la playlist
  - uris (string, optional): Una lista separada por comas de URIs de Spotify a añadir, pueden ser URIs de pistas o episodios
  - types (boolean, optional): Una lista separada por comas de tipos en el mismo orden que los IDs
  - ids (string, optional): Una lista separada por comas de IDs en el mismo orden que los tipos
- Devuelve: Elementos añadidos a la playlist
- Ejemplo: createPlaylist("playlist123")
changePlaylistDetails
- Descripción: Cambiar el nombre de una playlist y su estado público/privado
- Parámetros:
  - playlist_id (string): El ID de Spotify de la playlist
  - name (string, optional): El nuevo nombre de la playlist
  - public (boolean, optional): El nuevo estado público/privado de la playlist
  - description (string, optional): Valor para la descripción de la playlist
- Devuelve: Detalles de la playlist cambiados
- Ejemplo: changePlaylistDetails("playlist123", "new new playlist")

Configuración

Requisitos previos

Node.js v16+
Una cuenta de Spotify Premium
Una aplicación de desarrollador de Spotify registrada

Instalación

git clone https://github.com/iankan04/MCP-Spotify.git
cd mcp-spotify
npm install
npm run build

Creación de una aplicación de desarrollador de Spotify

Ve al Spotify Developer Dashboard
Inicia sesión con tu cuenta de Spotify
Haz clic en el botón "Create an App"
Completa el nombre y la descripción de la aplicación
Acepta los Términos de Servicio y haz clic en "Create"
En el panel de tu nueva aplicación, verás tu Client ID
Haz clic en "Show Client Secret" para revelar tu Client Secret
Haz clic en "Edit Settings" y añade una Redirect URI (por ejemplo, http://localhost:8000/callback)
Guarda tus cambios

Configuración de la API de Spotify

Crea un archivo .env.local en la raíz del proyecto (puedes copiar y modificar el ejemplo proporcionado):

SPOTIFY_CLIENT_ID='Your client_id'
SPOTIFY_CLIENT_SECRET='Your client_secret'
SPOTIFY_REDIRECT_URI='Your redirect_uri (i.e. http://127.0.0.1:8000/callback'

Asegúrate de que tu redirect_uri siga la Spotify Developer Settings más reciente.

Proceso de autenticación

La API de Spotify utiliza OAuth 2.0 para la autenticación. Sigue estos pasos para autenticar tu aplicación:

Abre dos pantallas de terminal. En una, ejecuta

redis-server

En la otra, ejecuta

npm run auth

El script generará una URL de autorización. Abre esta URL en tu navegador web.
Se te pedirá que inicies sesión en Spotify y autorices tu aplicación.
Después de la autorización, Spotify te redirigirá a tu redirect URI especificada con un parámetro code en la URL.
El script de autenticación intercambiará automáticamente este código por tokens de acceso y de actualización.
Estos tokens se guardarán en la base de datos de Redis y se actualizarán automáticamente cuando se soliciten.

Integración con Claude Desktop

Para usar tu servidor MCP con Claude Desktop, añádelo a tu configuración de Claude:

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["MCP-Spotify/build/index.js"]
    }
  }
}

Si Claude está en ejecución, reinicia la aplicación y deberías ver "spotify" como una nueva herramienta