spotify-mcp
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-- utilizahttpxasíncrono directamente (asíncrono nativo, sin envoltorioasyncio.to_thread)Módulo único --
server.py,spotify_api.py,utils.pyconsolidados en un solo archivoFastMCP -- decoradores
@mcp.tool()limpios en lugar de ToolModel manual + enrutamiento match/case2 dependencias -- solo
mcp+httpx(antesmcp+spotipy+python-dotenv)OAuth explícito --
spotify-mcp --authpara 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 APIClaude envía llamadas a herramientas a través del protocolo MCP
El servidor las traduce en solicitudes a la API web de Spotify usando
httpxLos tokens OAuth se autorrefrescan; autenticación inicial mediante
spotify-mcp --authLos resultados se analizan en un JSON conciso y se devuelven a Claude
Herramientas disponibles
Herramienta | Acciones | Descripción |
|
| Controla la reproducción de música y el volumen |
| -- | Busca pistas, álbumes, artistas, listas de reproducción |
|
| Ver y gestionar la cola de reproducción |
| -- | Obtener información detallada del elemento mediante URI de Spotify |
|
| Gestión completa de listas de reproducción |
|
| Gestionar canciones guardadas y comprobar la biblioteca |
| -- | Obtener pistas reproducidas recientemente con marcas de tiempo |
|
| 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 oneRequisitos 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
Crea una nueva aplicación
Establece el URI de redirección en
http://127.0.0.1:8080/callbackAnota 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 --authEsto 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.gitAñ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 |
| Sí | -- | ID de cliente de la aplicación Spotify |
| Sí | -- | Secreto de cliente de la aplicación Spotify |
| No |
| URI de redirección OAuth |
| No |
| Ruta del archivo de caché de tokens |
Solución de problemas
Primera ejecución: Ejecuta
spotify-mcp --authpara completar el flujo OAuth antes de usarlo con un cliente MCPToken caducado: Los tokens se autorrefrescan. Si los problemas persisten, vuelve a ejecutar
--authSin dispositivo activo: Asegúrate de que Spotify esté abierto y reproduciéndose en al menos un dispositivo
Asegúrate de que
uvesté 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-mcpResumen de cambios de la API de Spotify de febrero de 2026
Cambio | Impacto | Estado |
Límite de búsqueda | Menos resultados por búsqueda | Adaptado |
Endpoints de lista de reproducción | Las URLs de los endpoints cambiaron | Adaptado |
Campo de respuesta | Análisis actualizado | Adaptado |
Endpoints GET por lotes eliminados | Se deben obtener individualmente | Adaptado |
Campo | Ya no está disponible | Gestionado |
Modo desarrollador: límite de 5 usuarios, se requiere Premium | Restricción de acceso | Documentado |
Créditos
Proyecto original: varunneal/spotify-mcp por Varun Srivastava (Licencia MIT)
Colaboradores originales: @jamiew, @davidpadbury, @manncodes, @hyuma7, @aanurraj, @JJGO y otros
Mantenido con: Claude Code (Anthropic)
Licencia
Licencia MIT -- consulta LICENSE para más detalles.
Available Tools
6 toolsSpotifyGetInfoC
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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for Producer/Riffusion AI music generation
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceAn 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
- AlicenseAqualityBmaintenanceMCP server for the Spotify Web API — gives Claude and other AI assistants tools to search music, control playback, manage playlists, library, and podcasts.475MIT
- AlicenseNot gradedqualityDmaintenanceAn 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 npm9ISC
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables searching and managing Spotify music, playlists, artists, albums, and audiobooks through natural language.2493 npmMIT