Skip to main content
Glama

spotify-mcp

Un servidor del Protocolo de Contexto de Modelo (MCP) que conecta Claude con Spotify. Controla tu reproducción de Spotify, busca música, gestiona listas de reproducción y más, todo a través de una conversación natural con Claude.

Aviso de bifurcación: Este proyecto es una bifurcación de varunneal/spotify-mcp y está actualizado para los cambios de la API web de Spotify de febrero de 2026. Creado y mantenido con Claude Code.

¿Qué ha cambiado? (v0.4.0)

Reescritura de la arquitectura

  • Se eliminó spotipy -- utiliza httpx asíncrono directamente (asíncrono nativo, sin envoltorio asyncio.to_thread)

  • Módulo único -- server.py, spotify_api.py, utils.py consolidados en un solo archivo

  • FastMCP -- decoradores @mcp.tool() limpios en lugar de ToolModel manual + enrutamiento match/case

  • 2 dependencias -- solo mcp + httpx (antes mcp + spotipy + python-dotenv)

  • OAuth explícito -- spotify-mcp --auth para la configuración inicial, autorrefresco en usos posteriores

Características (preservadas de la v0.3.0)

  • Iniciar, pausar y saltar reproducción

  • Buscar pistas, álbumes, artistas y listas de reproducción

  • Obtener información detallada sobre cualquier elemento de Spotify

  • Gestionar la cola de reproducción

  • CRUD completo de listas de reproducción (crear, leer, actualizar, eliminar pistas)

  • Recuperar canciones que te gustan/guardadas con enriquecimiento de género opcional

  • Adaptado para los cambios de la API de Spotify de febrero de 2026

Related MCP server: Spotify MCP Server

Cómo funciona

Claude <--MCP (stdio)--> spotify-mcp <--httpx async--> Spotify Web API
  1. Claude envía llamadas a herramientas a través del protocolo MCP

  2. El servidor las traduce en solicitudes a la API web de Spotify usando httpx

  3. Los tokens OAuth se autorrefrescan; autenticación inicial mediante spotify-mcp --auth

  4. Los resultados se analizan en un JSON conciso y se devuelven a Claude

Herramientas disponibles

Herramienta

Acciones

Descripción

spotify_playback

get, start, pause, skip, previous, volume

Controla la reproducción de música y el volumen

spotify_search

--

Busca pistas, álbumes, artistas, listas de reproducción

spotify_queue

get, add

Ver y gestionar la cola de reproducción

spotify_get_info

--

Obtener información detallada del elemento mediante URI de Spotify

spotify_playlist

get, get_tracks, add_tracks, remove_tracks, change_details, create, delete

Gestión completa de listas de reproducción

spotify_liked_songs

get, get_with_genres, like, unlike, check

Gestionar canciones guardadas y comprobar la biblioteca

spotify_recently_played

--

Obtener pistas reproducidas recientemente con marcas de tiempo

spotify_devices

list, transfer

Listar dispositivos y transferir la reproducción

Arquitectura

src/spotify_mcp/
  __init__.py   # Entry point (stdio / --auth)
  server.py     # FastMCP server, API client, parsers — all in one

Requisitos previos

  • Python 3.12+

  • Cuenta de Spotify Premium (requerida para el acceso a la API en modo desarrollador desde febrero de 2026)

  • Credenciales de Aplicación de desarrollador de Spotify

Configuración

1. Crear una aplicación de desarrollador de Spotify

  1. Ve a developer.spotify.com/dashboard

  2. Crea una nueva aplicación

  3. Establece el URI de redirección en http://127.0.0.1:8080/callback

  4. Anota tu ID de cliente y Secreto de cliente

Importante (febrero de 2026): Las aplicaciones en modo desarrollador están limitadas a 5 usuarios autorizados y requieren que el propietario de la aplicación tenga Spotify Premium.

2. Autenticación inicial

Ejecuta el flujo de autenticación una vez para obtener tu token OAuth:

SPOTIFY_CLIENT_ID=your_id SPOTIFY_CLIENT_SECRET=your_secret uv run spotify-mcp --auth

Esto abre un navegador para iniciar sesión en Spotify y luego guarda el token en ~/.spotify_mcp_cache.json.

3. Añadir al cliente MCP

Ejecutar localmente (recomendado)

git clone https://github.com/verIdyia/spotify-mcp.git

Añadir a tu configuración de MCP (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "spotify": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spotify-mcp",
        "run",
        "spotify-mcp"
      ],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
      }
    }
  }
}

Ejecutar con uvx

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": [
        "--python", "3.12",
        "--from", "git+https://github.com/verIdyia/spotify-mcp",
        "spotify-mcp"
      ],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
      }
    }
  }
}

Variables de entorno

Variable

Requerido

Predeterminado

Descripción

SPOTIFY_CLIENT_ID

Sí

--

ID de cliente de la aplicación Spotify

SPOTIFY_CLIENT_SECRET

Sí

--

Secreto de cliente de la aplicación Spotify

SPOTIFY_REDIRECT_URI

No

http://127.0.0.1:8080/callback

URI de redirección OAuth

SPOTIFY_CACHE_PATH

No

~/.spotify_mcp_cache.json

Ruta del archivo de caché de tokens

Solución de problemas

  1. Primera ejecución: Ejecuta spotify-mcp --auth para completar el flujo OAuth antes de usarlo con un cliente MCP

  2. Token caducado: Los tokens se autorrefrescan. Si los problemas persisten, vuelve a ejecutar --auth

  3. Sin dispositivo activo: Asegúrate de que Spotify esté abierto y reproduciéndose en al menos un dispositivo

  4. Asegúrate de que uv esté actualizado -- se recomienda la versión >=0.54

Depuración

Inicia el inspector MCP:

npx @modelcontextprotocol/inspector uv --directory /path/to/spotify-mcp run spotify-mcp

Resumen de cambios de la API de Spotify de febrero de 2026

Cambio

Impacto

Estado

Límite de búsqueda limit reducido de 50 a 10

Menos resultados por búsqueda

Adaptado

Endpoints de lista de reproducción /tracks -> /items

Las URLs de los endpoints cambiaron

Adaptado

Campo de respuesta tracks -> items

Análisis actualizado

Adaptado

Endpoints GET por lotes eliminados

Se deben obtener individualmente

Adaptado

Campo popularity eliminado de las pistas

Ya no está disponible

Gestionado

Modo desarrollador: límite de 5 usuarios, se requiere Premium

Restricción de acceso

Documentado

Créditos

Licencia

Licencia MIT -- consulta LICENSE para más detalles.

Available Tools

6 tools
SpotifyGetInfoC

Get detailed information about a Spotify item...

Inputs: item_uri (required).

SpotifyLikedSongsC

Get user's liked (saved) songs from Spotify library.

Inputs: action (required), limit.

SpotifyPlaybackC

Manages the current playback...

Inputs: action (required), spotify_uri, num_skips.

SpotifyPlaylistC

Manage Spotify playlists.

Inputs: action (required), playlist_id, track_ids, name, +2 more.

SpotifyQueueC

Manage the playback queue - get the queue or add tracks.

Inputs: action (required), track_id.

SpotifySearchC

Search for tracks, albums, artists, or playlists on Spotify.

Inputs: query (required), qtype, limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting different Spotify resources: GetInfo for item details, LikedSongs for saved songs, Playback for current playback control, Playlist for playlist management, Queue for queue operations, and Search for finding content. There is no overlap or ambiguity between these functions.

    Naming Consistency5/5

    All tools follow a consistent 'Spotify' prefix with descriptive noun-based naming (e.g., SpotifyGetInfo, SpotifyPlaylist). The pattern is uniform across all six tools, making them easily identifiable and predictable.

    Tool Count5/5

    With 6 tools, this server is well-scoped for Spotify integration, covering key areas like playback, playlists, search, and user library. Each tool serves a specific, necessary function without bloat or redundancy.

    Completeness4/5

    The toolset covers core Spotify functionalities including search, playback control, playlist management, and user data access. Minor gaps might include operations like following artists or managing user profile settings, but the provided tools support most common workflows effectively.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      An MCP server that enables users to control Spotify playback, search for music, and manage playlists through MCP-compatible clients. It supports features like track recommendations and playback management using secure OAuth authentication.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for the Spotify Web API — gives Claude and other AI assistants tools to search music, control playback, manage playlists, library, and podcasts.
      47
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An unofficial MCP server that provides access to Spotify's Web API through the Model Context Protocol, enabling AI assistants to search music, manage playlists, and control playback.
      29 npm
      9
      ISC
    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that enables searching and managing Spotify music, playlists, artists, albums, and audiobooks through natural language.
      24
      93 npm
      MIT