mcp-spotify-cli
Allows controlling Spotify playlists, playback, volume, and search using natural language.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-spotify-cli Play my Discover Weekly playlist on shuffle"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Spotify CLI
Agente de línea de comandos (CLI) para controlar Spotify mediante lenguaje natural. Implementa la arquitectura Model Context Protocol (MCP) para separar el servidor de herramientas de Spotify del cliente LLM. Soporta múltiples proveedores de IA (Groq, Gemini, OpenAI).
Arquitectura
El proyecto consta de dos componentes principales:
mcp_spotify/server.py: Servidor MCP que expone la API de Spotify (Spotipy) como tools estandarizadas.mcp_spotify/agent.py: Cliente que interactúa con el usuario, procesa el lenguaje natural mediante adaptadores LLM y ejecuta las tools del servidor con un límite de iteraciones de seguridad para prevenir consumo excesivo de tokens.
Related MCP server: Spotify MCP Server
Funcionalidades (Tools)
get_current_track: Obtiene información del track en reproducción.list_devices: Lista dispositivos activos.search_track/search_playlist: Búsqueda en el catálogo de Spotify.get_my_playlists: Retorna las playlists guardadas por el usuario autenticado.play,pause,next_track,previous_track: Control básico de reproducción.set_volume,set_shuffle,set_repeat: Control de estado y preferencias.
Requisitos
Python 3.12+
Gestor de paquetes
uv.Cuenta de Spotify Premium (necesaria para los endpoints de control de reproducción).
App registrada en Spotify Developer Dashboard para obtener Client ID y Client Secret.
API Keys de los proveedores LLM a utilizar (Groq, Google GenAI, OpenAI).
Instalación
Clonar el repositorio.
Instalar dependencias utilizando
uv:uv sync(Dependencias principales: mcp, spotipy, google-genai, openai, python-dotenv).
Configurar el archivo
.enven la raíz del proyecto.
Configuración (.env)
Crear un archivo .env con las siguientes variables:
SPOTIPY_CLIENT_ID="tu_client_id"
SPOTIPY_CLIENT_SECRET="tu_client_secret"
SPOTIPY_REDIRECT_URI="[http://127.0.0.1:8080](http://127.0.0.1:8080)"
GROQ_API_KEY="tu_api_key_de_groq"
GEMINI_API_KEY="tu_api_key_de_google"
OPENAI_API_KEY="tu_api_key_de_openai"Ejecución
Ejecutar el agente especificando el proveedor y, opcionalmente, el modelo.
Sintaxis:
uv run mcp-spotify <proveedor> [modelo]Ejemplo:
Usar Groq (default: llama-3.3-70b-versatile)
uv run mcp-spotify groqUsar Gemini (default: models/gemini-2.0-flash)
uv run mcp-spotify geminiUsar Gemini con un modelo específico
uv run mcp-spotify gemini models/gemini-1.5-flashModelo de mayor capacidad de razonamiento
uv run mcp-spotify gemini models/gemini-2.5-proUsar un modelo específico de OpenAI
uv run mcp-spotify openai gpt-4oUso
Una vez iniciado, el prompt permite ingresar comandos en lenguaje natural:
"reproducir mi playlist 'nombre_de_tu_playlist' en modo shuffle"
"baja el volumen al 50% y pasá a la siguiente canción"
"¿qué está sonando?"
Créditos
🛠️ Nota de desarrollo y aprendizaje
Este proyecto es una iniciativa de aprendizaje personal con fines educativos. He desarrollado este agente utilizando el Model Context Protocol (MCP) y bibliotecas de Python, contando con la asistencia de Inteligencia Artificial para la estructura del código, la resolución de errores y la implementación de buenas prácticas de desarrollo.
Comparto este repositorio con la comunidad como una forma de documentar mi proceso de aprendizaje y con la esperanza de que pueda servir como punto de partida o referencia para alguien que esté explorando la integración de LLMs con APIs externas.
¡Cualquier feedback, sugerencia de mejora o pull request es más que bienvenido!
Available Tools
12 toolsget_current_trackA
Devuelve la canción que está sonando ahora mismo.
Inputs: no named parameters. Returns: result
get_my_playlistsA
Devuelve las playlists del usuario autenticado con sus URIs. Usá siempre esta herramienta primero si el usuario pide reproducir 'mi playlist' o 'mis playlists'.
Inputs: no named parameters. Returns: result
list_devicesB
Lista los dispositivos Spotify disponibles.
Inputs: no named parameters. Returns: result
next_trackA
Salta a la siguiente canción y devuelve el nombre del tema.
Inputs: no named parameters. Returns: result
pauseB
Pausa la reproducción.
Inputs: no named parameters. Returns: result
playA
Reproduce una canción o playlist dado su URI de Spotify. Si no se pasa URI, reanuda la reproducción actual. Ejemplos de URI: spotify:track:xxx o spotify:playlist:xxx
Inputs: uri. Returns: result
previous_trackA
Vuelve a la canción anterior y devuelve el nombre del tema.
Inputs: no named parameters. Returns: result
search_playlistC
Busca una playlist en Spotify y devuelve el URI para reproducirla.
Inputs: query (required). Returns: result
search_trackC
Busca una canción en Spotify y devuelve el URI para reproducirla.
Inputs: query (required). Returns: result
set_repeatA
Cambia el modo de repetición. Valores válidos: 'off', 'track', 'context'
off: sin repetición
track: repite la canción actual
context: repite el álbum/playlist
Inputs: mode (required). Returns: result
set_shuffleC
Activa o desactiva el modo aleatorio (shuffle).
Inputs: state (required). Returns: result
set_volumeC
Ajusta el volumen. Valor entre 0 y 100.
Inputs: volume_percent (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct resource or playback action: playback state, devices, track search, playlist search, user playlists, and specific playback controls. There is no meaningful overlap between search_track/search_playlist or between play/pause/next/previous.
Names are consistently snake_case and mostly follow verb_noun or action_noun patterns (get_current_track, list_devices, set_volume). Minor deviations exist with bare verbs play/pause and next_track/previous_track, but the set remains predictable.
Twelve tools is well-scoped for Spotify playback control, with each tool covering a distinct operation. The count is neither thin nor excessive for the domain.
Core playback is covered: play, pause, skip, volume, shuffle, repeat, current track, search, and playlists. However, notable gaps remain: no device transfer/selection despite list_devices, no seek/position control, no queue management, and no playback state beyond the current track.
Maintenance
Related MCP Connectors
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Package intelligence MCP for AI agents — 22 tools, 19 ecosystems, AGPL SDK, free.
LLM Orchestration Agent (Mcp)
Related MCP Servers
- AlicenseBqualityCmaintenanceA lightweight Model Context Protocol server that enables AI assistants like Cursor & Claude to control Spotify playback and manage playlists.22513MIT
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables controlling Spotify playback through natural language commands in MCP clients like Cursor or Claude for Desktop.1-
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables AI assistants like Claude Desktop to interact with Spotify's music streaming service, supporting playback control, playlist management, music search, and user profile access.412MIT
- AlicenseAqualityCmaintenanceMCP server for Spotify that enables playlist building and music discovery through 19 tools, allowing LLM agents to search tracks/artists/albums, manage playlists, control playback, and access personal listening data.2031 PyPI1MIT