ytmusic-mcp

Un servidor MCP que envuelve ytmusicapi para que Claude (o cualquier cliente MCP) pueda buscar en YouTube Music, gestionar tus listas de reproducción y leer tu historial de escucha.

Herramientas

No incluido (v1): Recomendaciones basadas en BPM. YouTube Music no expone datos de tempo, por lo que se necesitaría una segunda fuente de datos (por ejemplo, una API de análisis de audio) — un objetivo a largo plazo para una versión futura, no parte de esta versión.

Related MCP server: mcp-server-youtube

Configuración

1. Instalar dependencias

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Autenticación

No existe una API oficial de YouTube Music, por lo que ytmusicapi se autentica reutilizando las cabeceras de tu sesión de navegador iniciada.

1. Abre music.youtube.com en Firefox (recomendado — su copia de cabeceras sin procesar es más fiable que la de Chrome) mientras estás conectado.

2. Abre DevTools (Cmd+Option+I / F12) → pestaña Red → filtra por browse.

3. Haz clic en una lista de reproducción, o recarga la página, para activar una solicitud POST de browse.

4. Haz clic en esa solicitud → pestaña Encabezados → activa Encabezados sin procesar → selecciona y copia todo el bloque.

5. Pégalo en un nuevo archivo llamado raw_headers.txt en la raíz del proyecto y guárdalo.

6. Ejecuta:

   python scripts/setup_auth_from_file.py

   Esto escribe headers_auth.json y elimina raw_headers.txt.

Alternativamente, python scripts/setup_auth.py hace lo mismo mediante un prompt interactivo en la terminal en lugar de un archivo, si prefieres pegar directamente.

headers_auth.json equivale a tu sesión iniciada — nunca lo subas al control de versiones ni lo compartas. Ya está en .gitignore.

Verifica que la autenticación funciona antes de continuar:

python scripts/test_search.py

Estas cabeceras caducan/rotan periódicamente. Si las herramientas empiezan a fallar con un error de autenticación, repite este paso.

3. Añadir a Claude Code

claude mcp add ytmusic -s user \
  -e YTMUSIC_AUTH_PATH="$(pwd)/headers_auth.json" \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

-s user lo hace disponible en cualquier sesión de Claude Code, no solo en este directorio. Usa rutas absolutas para el intérprete de Python, server.py y YTMUSIC_AUTH_PATH, ya que el servidor puede lanzarse desde cualquier directorio de trabajo.

Para otros clientes MCP (Claude Desktop, etc.), apúntalos al mismo comando y variable de entorno usando su formato de configuración respectivo.

Manejo de errores

Las llamadas a herramientas traducen modos de fallo comunes en mensajes claros en lugar de trazas de error sin procesar:

• Autenticación faltante/caducada/incorrecta → te indica que vuelvas a ejecutar scripts/setup_auth_from_file.py.

• Límite de velocidad (HTTP 429) → te indica que esperes y lo intentes de nuevo.

• Contenido restringido/bloqueado → se informa como no disponible en lugar de fallar.

• Errores de red → se informan directamente.

Licencia

MIT — ver LICENSE.