spotify-mcp

Ein MCP-Server, der spotipy kapselt, damit Claude (oder ein beliebiger MCP-Client) Spotify durchsuchen und Wiedergabelisten, gespeicherte Titel, Künstlerkataloge und Entdeckungssignale lesen kann.

Speziell als Spotify-Backend von re-com entwickelt – bewusst leselastig, kein Server zur Wiedergabesteuerung. Er unterstützt zwar das Erstellen von Wiedergabelisten und das Hinzufügen von Titeln (damit aus einer re-com-Empfehlungsliste eine echte Wiedergabeliste werden kann), bietet aber keine Play-/Pause-/Warteschlangensteuerung; schau dir dafür einen der zahlreichen auf Wiedergabe spezialisierten Spotify-MCP-Server an, die es bereits gibt.

Werkzeuge

Eine echte Einschränkung, deutlich gesagt: Spotify schränkt /recommendations und artist_related_artists für API-Apps ein, die nach November 2024 erstellt wurden und keinen „Extended Quota Mode“ haben (eine manuelle Freigabe, die Spotify nur zögerlich erteilt). Wenn deine App ihn nicht hat, liefern get_recommendations und get_related_artists einen 403 – handle_errors wandelt das in eine klare Meldung um statt in einen rohen Traceback, und re-coms spotify_client.py behandelt es als ein nicht verfügbares Signal, nicht als schwerwiegenden Fehler. search_music, Wiedergabelisten, gespeicherte Titel und Künstler-Toptitel sind nicht betroffen.

Andere Claude-Code-Projekte auf diesem Rechner (z. B. re-com) rufen diese Werkzeuge auf, indem sie diesen Server über MCP starten, anstatt selbst mit spotipy/Spotify zu kommunizieren – nur hier liegen die Spotify-Anmeldedaten.

Einrichtung

1. Eine Spotify-App registrieren

1. Gehe zum Spotify Developer Dashboard und erstelle eine App.

2. Füge eine Weiterleitungs-URI hinzu, die zu SPOTIFY_REDIRECT_URI passt (Standard http://127.0.0.1:8888/callback – auf diesem Port muss nichts lauschen; siehe Schritt 3).

3. Notiere dir die Client-ID und das Client-Geheimnis der App.

2. Abhängigkeiten installieren

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

3. Authentifizieren

export SPOTIFY_CLIENT_ID="..."
export SPOTIFY_CLIENT_SECRET="..."
python scripts/setup_auth_spotify.py

Dies gibt eine Autorisierungs-URL aus, wartet darauf, dass du dich anmeldest und die URL, zu der du weitergeleitet wirst, wieder einfügst (funktioniert problemlos über SSH/headless – nichts muss den Weiterleitungsport binden), und schreibt das resultierende Token in .spotify_cache (Pfad über SPOTIFY_CACHE_PATH konfigurierbar).

.spotify_cache entspricht deiner angemeldeten Sitzung – committe oder teile sie niemals. Sie ist bereits in der Gitignore. Tokens werden nach dem Zwischenspeichern automatisch aktualisiert; führe dieses Skript nur erneut aus, wenn die Aktualisierung selbst fehlschlägt (z. B. weil das Client-Geheimnis der App rotiert wurde oder du den Zugriff in deinen Spotify-Kontoeinstellungen widerrufen hast) oder wenn SCOPE in server.py neue Berechtigungen erhält (lösche zuerst .spotify_cache, damit der Authentifizierungsablauf erneut um Zustimmung bittet – ein veraltetes zwischengespeichertes Token übernimmt neue Bereiche nicht von selbst).

4. Zu Claude Code hinzufügen

claude mcp add spotify -s user \
  -e SPOTIFY_CLIENT_ID="..." \
  -e SPOTIFY_CLIENT_SECRET="..." \
  -e SPOTIFY_CACHE_PATH="$(pwd)/.spotify_cache" \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

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

Für andere MCP-Clients (Claude Desktop usw.) verweise auf denselben Befehl und dieselben Umgebungsvariablen mit dem jeweiligen Konfigurationsformat.

Testen

Die Unit-Test-Suite (tests/) läuft gegen einen selbstgebauten Fake-spotipy.Spotify-Client – weder Netzwerkzugriff noch Spotify-Anmeldedaten erforderlich:

pip install -e ".[dev]"
pytest

Fehlerbehandlung

Werkzeugaufrufe übersetzen häufige Fehlerfälle in klare Meldungen statt in rohe Tracebacks:

• Fehlende/abgelaufene Authentifizierung (401) → weist darauf hin, den Authentifizierungsschritt zu wiederholen.

• Eingeschränkt/verboten (403) → weist darauf hin, dass es sich wahrscheinlich um eine Zugriffsbeschränkung der Spotify-API handelt (siehe den Hinweis zu Empfehlungen/verwandten Künstlern oben) oder um einen fehlenden OAuth-Bereich.

• Ratenbegrenzung (429) → weist zum Warten an, einschließlich des Retry-After-Hinweises, falls Spotify einen gesendet hat.

• Jeder andere API- oder OAuth-Fehler wird direkt gemeldet statt als roher Traceback.

Lizenz

MIT – siehe LICENSE.