Skip to main content
Glama
mcp-spotify-cli

mcp-spotify-cli

by walterreiner

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

  1. Clonar el repositorio.

  2. Instalar dependencias utilizando uv:

    uv sync

    (Dependencias principales: mcp, spotipy, google-genai, openai, python-dotenv).

  3. Configurar el archivo .env en 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 groq

Usar Gemini (default: models/gemini-2.0-flash)

uv run mcp-spotify gemini

Usar Gemini con un modelo específico

uv run mcp-spotify gemini models/gemini-1.5-flash

Modelo de mayor capacidad de razonamiento

uv run mcp-spotify gemini models/gemini-2.5-pro

Usar un modelo específico de OpenAI

uv run mcp-spotify openai gpt-4o

Uso

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 tools
get_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

    A3.5/5.0

    Scored across 12 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers