ytmusic-mcp

Ein MCP-Server, der ytmusicapi kapselt, damit Claude (oder jeder andere MCP-Client) YouTube Music durchsuchen, Ihre Playlists verwalten und Ihren Hörverlauf lesen kann.

Werkzeuge

Nicht enthalten (v1): BPM-basierte Empfehlungen. YouTube Music stellt keine Tempo-Daten bereit, daher wäre eine zweite Datenquelle erforderlich (z. B. eine Audioanalyse-API) – ein ehrgeiziges Ziel für eine zukünftige Version, nicht Teil dieses Builds.

Related MCP server: mcp-server-youtube

Einrichtung

1. Abhängigkeiten installieren

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

2. Authentifizieren

Es gibt keine offizielle YouTube Music API, daher authentifiziert sich ytmusicapi durch Wiederverwendung von Headern aus Ihrer angemeldeten Browsersitzung.

1. Öffnen Sie music.youtube.com in Firefox (empfohlen – das Kopieren der Roh-Header ist zuverlässiger als in Chrome), während Sie angemeldet sind.

2. Öffnen Sie die Entwicklertools (Cmd+Option+I / F12) → Netzwerk-Tab → filtern Sie nach browse.

3. Klicken Sie auf eine Playlist oder laden Sie die Seite neu, um eine browse-POST-Anfrage auszulösen.

4. Klicken Sie auf diese Anfrage → Header-Tab → schalten Sie Roh-Header um → wählen Sie den gesamten Block aus und kopieren Sie ihn.

5. Fügen Sie ihn in eine neue Datei mit dem Namen raw_headers.txt im Projektstammverzeichnis ein und speichern Sie sie.

6. Führen Sie aus:

   python scripts/setup_auth_from_file.py

   Dies schreibt headers_auth.json und löscht raw_headers.txt.

Alternativ macht python scripts/setup_auth.py dasselbe über eine interaktive Terminaleingabe anstelle einer Datei, falls Sie direkt einfügen möchten.

headers_auth.json entspricht Ihrer angemeldeten Sitzung – committen oder teilen Sie es niemals. Es ist bereits in der Git-Ignorierliste.

Überprüfen Sie, ob die Authentifizierung funktioniert, bevor Sie fortfahren:

python scripts/test_search.py

Diese Header laufen ab/rotieren regelmäßig. Wenn Tools mit einem Authentifizierungsfehler fehlschlagen, wiederholen Sie diesen Schritt.

3. Zu Claude Code hinzufügen

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

-s user macht es in jeder Claude Code-Sitzung verfügbar, nicht nur in diesem Verzeichnis. Verwenden Sie absolute Pfade für den Python-Interpreter, server.py und YTMUSIC_AUTH_PATH, da der Server aus jedem Arbeitsverzeichnis gestartet werden kann.

Für andere MCP-Clients (Claude Desktop usw.) verweisen Sie sie mit dem jeweiligen Konfigurationsformat auf denselben Befehl und dieselbe Umgebungsvariable.

Fehlerbehandlung

Tool-Aufrufe übersetzen häufige Fehlermodi in klare Meldungen anstelle von rohen Tracebacks:

• Fehlende/abgelaufene/fehlerhafte Authentifizierung → fordert Sie auf, scripts/setup_auth_from_file.py erneut auszuführen.

• Ratenbegrenzung (HTTP 429) → fordert Sie auf, zu warten und es erneut zu versuchen.

• Gesperrte/eingeschränkte Inhalte → werden als nicht verfügbar gemeldet, anstatt abzustürzen.

• Netzwerkfehler → werden direkt gemeldet.

Lizenz

MIT – siehe LICENSE.