auxcord-mcp

Servidor MCP de Spotify

Un servidor de Protocolo de Contexto de Modelo (MCP) que brinda a los asistentes de IA (Claude Desktop, Cursor, Antigravity o tus propios agentes) control sobre Spotify: reproducción, dispositivos, la cola, búsqueda, tu biblioteca y listas de reproducción.

Destacados

• 32 herramientas que cubren reproducción, dispositivos, la cola, búsqueda en el catálogo, tu historial de escucha y biblioteca, y gestión de listas de reproducción, incluida la portada personalizada.
• 6 recursos ambientales (spotify://...) que brindan al asistente contexto como qué está sonando, tu cola y tu perfil de gustos, sin necesidad de una llamada de herramienta.
• Errores amigables para agentes. Los fallos regresan como JSON estructurado con un error_code y orientación de recuperación (por ejemplo, "no hay dispositivo activo, llama a spotify_get_available_devices") en lugar de errores HTTP crudos. Los argumentos inválidos se rechazan antes de llegar a Spotify.
• Respuestas compactas. Los payloads de Spotify se recortan a los campos que un asistente realmente necesita, para que usen menos de su ventana de contexto.
• Funciona localmente o por HTTP. Se ejecuta sobre stdio para clientes de escritorio o como un servidor HTTP de transmisión sin estado, y maneja el inicio de sesión OAuth 2.0 PKCE y la renovación de tokens por ti.

Descripción general

El servidor envuelve la API Web de Spotify como herramientas y recursos MCP. Un asistente conectado a él puede manejar solicitudes como "pon en cola tres pistas animadas de Daft Punk", "haz una lista de reproducción con mis pistas principales de este mes" o "mueve la reproducción a mi teléfono".

Inicia sesión con tu propia cuenta de Spotify, usando una aplicación de desarrollador de Spotify que tú creas (consulta Instalación). El control de reproducción requiere Spotify Premium.

Herramientas

Área	Herramientas
Reproducción	spotify_play, spotify_pause, spotify_skip_to_next, spotify_skip_to_previous, spotify_seek_to_position, spotify_set_volume, spotify_toggle_shuffle, spotify_set_repeat_mode, spotify_get_playback_state, spotify_get_currently_playing
Dispositivos	spotify_get_available_devices, spotify_transfer_playback
Cola	spotify_get_queue, spotify_add_to_queue
Catálogo	spotify_search_catalog, spotify_get_artist, spotify_get_album
Usuario y biblioteca	spotify_get_user_profile, spotify_get_top_tracks, spotify_get_top_artists, spotify_get_recently_played, spotify_get_saved_tracks
Listas de reproducción	spotify_create_playlist, spotify_get_user_playlists, spotify_get_playlist, spotify_get_playlist_items, spotify_add_tracks_to_playlist, spotify_remove_tracks_from_playlist, spotify_reorder_playlist_tracks, spotify_replace_playlist_tracks, spotify_update_playlist_details, spotify_upload_playlist_cover

Recursos: spotify://user/profile, spotify://user/top-tracks, spotify://user/top-artists, spotify://player/current, spotify://player/queue, spotify://playlist/{playlist_id}.

Limitaciones conocidas de la API de Spotify

Estos son límites del lado de Spotify, no errores de este servidor. Cada uno fue confirmado contra la API Web en vivo o el registro de cambios de Spotify.

• La visibilidad de las listas de reproducción no se puede configurar mediante la API. Spotify acepta public: false al crear y actualizar, pero la lista permanece pública. Por esa razón, las herramientas de listas de reproducción no ofrecen un parámetro public. Configura la visibilidad en la aplicación de Spotify. (hilo de la comunidad)
• El contenido de las listas de reproducción solo está disponible para listas que posees o en las que colaboras. Para otras listas, spotify_get_playlist devuelve metadatos con un note explicativo, y spotify_get_playlist_items devuelve un error PLAYLIST_CONTENTS_UNAVAILABLE.
• Los metadatos de artistas y pistas están reducidos. Spotify ya no devuelve genres, popularity o followers en artistas, popularity en pistas, o label / popularity en álbumes. Las pistas principales de artistas ya no están disponibles, así que usa spotify_search_catalog con artist:"Name" en su lugar.
• La búsqueda devuelve como máximo 10 resultados por tipo (5 por defecto), y limit + offset no puede superar 1000.
• La búsqueda de listas de reproducción oculta algunos resultados. Spotify devuelve algunos resultados de listas como null (aproximadamente 3 de cada 10 en pruebas en vivo). spotify_search_catalog los descarta e informa cuántos descartó en playlists_hidden_by_spotify. Si una página regresa mayormente o completamente oculta, prueba con la siguiente offset.
• Los conteos de pistas en listas pueden retrasarse. Justo después de agregar pistas, spotify_get_user_playlists puede informar un tracks_total desactualizado. spotify_get_playlist informa el conteo actual.

Uso

Después de instalar, agrega el servidor a tu cliente MCP. Para Claude Desktop, edita claude_desktop_config.json:

{
  "mcpServers": {
    "spotify": {
      "command": "/path/to/spotify-mcp-server/.venv/bin/python",
      "args": ["/path/to/spotify-mcp-server/main.py"]
    }
  }
}

Reinicia el cliente y pregunta algo como "¿Qué está sonando ahora? Agrega dos pistas similares a mi cola."

Para servir por HTTP de transmisión en su lugar, para configuraciones remotas o de múltiples clientes:

python main.py --transport http   # serves http://127.0.0.1:8000/mcp

Luego apunta tu cliente a http://127.0.0.1:8000/mcp. Usa --host y --port para cambiar la dirección.

Instalación

Necesitas Python 3.10 o más reciente y una cuenta de Spotify (Premium para control de reproducción).

1. Crea una aplicación de desarrollador de Spotify

1. Abre el Panel de desarrolladores de Spotify y haz clic en Crear aplicación.
2. Agrega la URI de redirección http://127.0.0.1:8888/callback. Debe coincidir exactamente, incluidos el puerto y la ruta.
3. En ¿Qué API/SDK planeas usar?, selecciona API Web, luego guarda.
4. Desde la Configuración de la aplicación, copia el ID de cliente y el Secreto de cliente.

Las aplicaciones nuevas comienzan en Modo de desarrollo: tu propia cuenta funciona de inmediato, y otras cuentas deben agregarse en Configuración > Gestión de usuarios.

2. Instala el servidor

git clone https://github.com/AtharvBagade/spotify-mcp-server.git
cd spotify-mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

3. Configura las credenciales

cp .env.example .env

Luego completa .env:

SPOTIFY_CLIENT_ID="your_client_id"
SPOTIFY_CLIENT_SECRET="your_client_secret"
SPOTIFY_REDIRECT_URI="http://127.0.0.1:8888/callback"

# Optional (defaults shown)
SPOTIFY_TOKEN_CACHE_PATH=".spotify_token.json"
MCP_SERVER_NAME="Spotify MCP Server"
MCP_HOST="127.0.0.1"
MCP_PORT=8000
LOG_LEVEL="INFO"

4. Inicia sesión una vez

python -c "from src.auth import SpotifyAuthManager; from src.config import load_settings; SpotifyAuthManager(load_settings()).get_valid_access_token()"

Se abre una ventana del navegador para que inicies sesión en Spotify. El token se guarda en caché en .spotify_token.json y se renueva automáticamente después. Si omites este paso, el mismo inicio de sesión ocurre en la primera llamada de herramienta. Los registros van a stderr; configura LOG_LEVEL=DEBUG para incluir rastreos completos.

Comentarios y contribuciones

Los informes de errores y las solicitudes de funciones son bienvenidos en Problemas de GitHub. Incluye el nombre de la herramienta, sus argumentos y el error_code que recibiste.

Para trabajar en el servidor, instala las dependencias de desarrollo y ejecuta las pruebas:

pip install -e ".[dev]"
pytest
ruff check src tests