SpotifyMCP

Ein MCP-Server, der die Spotify Web API kapselt und es KI-Assistenten (wie Claude) ermöglicht, die Wiedergabe zu steuern, den gesamten Katalog einschließlich Podcasts und Hörbüchern zu durchsuchen, Ihre Bibliothek und Playlists zu verwalten und Ihren Hörgeschmack zu verstehen.

Warum dieser

Die meisten Spotify-MCP-Server sind dünne Wrapper. Dieser ist darauf ausgelegt, der Standard zu sein:

• Vollständige API-Oberfläche — Jeder nicht veraltete Spotify-Web-API-Endpunkt, der mit einem Standard-Entwickler-Token aufrufbar ist, wird von einem Tool abgedeckt (Wiedergabe, Suche, Katalog, Hörbücher, Personalisierung, Bibliothek, Playlists, Folgen).

• Ehrlich bezüglich Veraltetem — Spotify hat Empfehlungen, verwandte Künstler, Audio-Features/-Analysen, Genre-Seeds und vorgestellte Playlists aus neuen Apps entfernt. Server, die diese weiterhin anbieten, liefern Tools, die zur Laufzeit fehlschlagen; dieser nicht.

• Getestet — Vollständige Unit-Test-Suite über den Client (Token-Refresh, Rate-Limiting, Pagination) und jeden Tool-Handler, plus ein End-to-End-MCP-Protokoll-Smoke-Test. Viele Alternativen haben null Tests.

• Alles paginiert — fetch_all bei Bibliotheks- und Playlist-Auflistungen geht jede Seite durch (begrenzt auf 500 Elemente), anstatt stillschweigend bei einer Seite von 50 abzuschneiden.

• Podcasts sind erstklassig — Episoden funktionieren überall: aktuell läuft, Warteschlange, Suche-und-Wiedergabe. Mehrere Konkurrenten können Podcasts überhaupt nicht sehen.

• Gerätebewusste Wiedergabe — Geräte auflisten, Wiedergabe übertragen und jeden Befehl auf ein bestimmtes Gerät ausrichten für Multi-Room-Setups.

• Robuste Authentifizierung — PKCE-Flow mit stillem Refresh, persistenter Token-Cache mit Modus 600, Headless-Paste-Flow (SPOTIFY_HEADLESS=1) für Server und Container.

Related MCP server: Spotify MCP Server

Funktionen

Wiedergabe (15 Tools) — Aktuelle Wiedergabe / Umfragen zur aktuellen Wiedergabe, Abspielen (per URI oder play_from_search, um direkt über einen Namen abzuspielen), Pause, Überspringen, Zurück, Suchen, Lautstärke, Zufallswiedergabe, Wiederholen, Warteschlange anzeigen/hinzufügen, Geräteliste, Wiedergabe übertragen.

Suche & Katalog — Einheitliche Suche über Titel/Künstler/Alben/Playlists/Shows/Episoden; tiefe Nachschlagefunktionen für Titel, Künstler, Künstler-Alben, Alben, Album-Titel, Shows, Show-Episoden, Episoden und Ihr Profil (get_me).

Hörbücher — Titel, Kapitel, Kapitel-Nachschlagefunktion und Ihre gespeicherten Hörbücher (von Spotify auf US/UK/CA/IE/NZ/AU beschränkt).

Personalisierung — Top-Titel und -Künstler über drei Zeiträume, zuletzt gespielt.

Bibliothek — Gespeicherte Titel/Alben/Shows/Episoden mit optionaler vollständiger Pagination; einheitliches Speichern/Entfernen/Prüfen über /me/library-URIs.

Playlists — Vollständiges CRUD plus Elementverwaltung (Hinzufügen/Entfernen/Neuordnen), Cover-Art-Abruf und benutzerdefinierter Cover-Upload (ugc-image-upload-Bereich für Upload erforderlich).

Folgen — Liste der gefolgten Künstler und Prüfung des Folge-Status.

Zusätzlich verfügbar: 7 MCP-Ressourcen (Profil, Player-Status, Warteschlange, Top-Titel/-Künstler, zuletzt gespielt, Playlists) und 4 Prompt-Vorlagen (DJ-Set, Stimmungs-Playlist, Geschmacksübersicht, Entdeckungsalternative).

Anforderungen & Einschränkungen

• Für die Wiedergabesteuerung ist Spotify Premium erforderlich (Abspielen, Pause, Überspringen, Suchen, Lautstärke, Zufallswiedergabe, Wiederholen, Warteschlange, Übertragen). Kostenlose Konten können sich authentifizieren und Such-/Katalog-/Bibliotheks-/Playlist-Tools verwenden, aber jeder Wiedergabebefehl schlägt mit einem Premium-Erforderlich-Fehler von Spotify fehl.

• Die fetch_all-Pagination durchläuft bis zu 500 Elemente pro Aufruf (schützt vor Endlosschleifen); darüber hinaus verwenden Sie limit/offset-Paginierung.

• Hörbuch-Tools sind von Spotify auf die USA, Großbritannien, Kanada, Irland, Neuseeland und Australien beschränkt.

• Der Entwicklermodus von Spotify erlaubt bis zu 5 autorisierte Benutzer pro App, bis ein erweitertes Kontingent gewährt wird.

Schnelleinrichtung

1. Spotify-App erstellen

Jeder Benutzer benötigt eine eigene Spotify-App, um eine Client-ID zu erhalten – so identifiziert Spotify, welche App API-Anfragen stellt.

1. Gehen Sie zum Spotify Developer Dashboard und erstellen Sie eine neue App.

2. Fügen Sie in den App-Einstellungen die folgende Redirect-URI exakt hinzu (Spotify lehnt die Anmeldung ab, wenn diese nicht übereinstimmt):

   http://127.0.0.1:8888/callback

3. Speichern Sie. Kopieren Sie Ihre Client-ID.

2. Authentifizieren

Führen Sie den folgenden Befehl einmal aus, um sich bei Ihrem Spotify-Konto anzumelden. Ersetzen Sie your_client_id_here durch die Client-ID aus Schritt 1. Es öffnet sich ein Browserfenster, und nach Ihrer Zustimmung werden Token unter ~/.spotify-mcp/tokens.json gespeichert. Der Server aktualisiert sie automatisch – Sie müssen dies nicht erneut tun.

macOS / Linux:

SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth

Headless / Remote-Hosts (kein Browser auf dem Rechner, auf dem der MCP-Server läuft):

SPOTIFY_HEADLESS=1 SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth

Die Auth-URL wird ausgegeben; führen Sie den Flow in einem beliebigen Browser durch (z. B. auf Ihrem Laptop) und fügen Sie dann die Redirect-URL zurück in die Eingabeaufforderung ein. Nützlich für Homelabs, CI und Agent-Laufzeiten.

Headless-Authentifizierung (Hosts ohne Browser)

Wenn Sie diesen MCP-Server auf einem Host ohne Browser ausführen (z. B. einer Cloud-VM, einem Docker-Container, einem Remote-Server), setzen Sie die Umgebungsvariable SPOTIFY_HEADLESS=1. Der Auth-Flow überspringt den lokalen HTTP-Callback-Server und fordert Sie stattdessen auf, die Redirect-URL einzufügen, nachdem Sie die App in Ihrem Browser autorisiert haben.

Schritte

1. Setzen Sie SPOTIFY_HEADLESS=1 in Ihrer Umgebung

2. Führen Sie den Server aus – er gibt eine URL zur Autorisierung der App aus

3. Öffnen Sie die URL in einem Browser auf einem anderen Rechner

4. Nach der Autorisierung leitet Ihr Browser zur Redirect-URI weiter

5. Kopieren Sie die vollständige URL aus der Adressleiste

6. Fügen Sie sie zurück in die Server-Eingabeaufforderung ein

Warum

Der Standard-Auth-Flow öffnet einen Browser über das open-Paket und führt einen lokalen HTTP-Callback-Server auf 127.0.0.1:8888 aus. Das bricht, wenn der MCP- Server auf einem Headless-Host (Homelab, CI, Agent-Laufzeit) läuft, wo kein Browser für open() vorhanden ist und der 127.0.0.1:8888-Callback nicht vom Rechner des Benutzers erreicht werden kann.

SPOTIFY_HEADLESS=1 wechselt zu einem Paste-URL-Flow: Die Auth-URL wird auf stdout ausgegeben, der Bediener führt den Flow in einem beliebigen Browser (seinem Laptop, Telefon) durch und fügt dann die vollständige Redirect-URL zurück. Der Code + State werden serverseitig extrahiert und ausgetauscht. Funktioniert über Rechner hinweg.

Windows (Eingabeaufforderung):

set SPOTIFY_CLIENT_ID=your_client_id_here && npx -y @novalux12/spotify-mcp@latest auth

Windows (PowerShell):

$env:SPOTIFY_CLIENT_ID="your_client_id_here"; npx -y @novalux12/spotify-mcp@latest auth

3. Claude Desktop konfigurieren

Öffnen Sie Ihre claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: Öffnen Sie Claude Desktop → Einstellungen → Entwickler → Konfiguration bearbeiten

Fügen Sie den mcpServers-Block hinzu (ersetzen Sie your_client_id_here durch Ihre Client-ID):

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@novalux12/spotify-mcp@latest"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here"
      }
    }
  }
}

Beenden und starten Sie Claude Desktop vollständig neu. Ein Hammersymbol im Chat-Eingabefeld bestätigt, dass der Server verbunden ist.

Alternative: Claude Code

Wenn Sie Claude Code verwenden, fügen Sie den Server hinzu, ohne JSON von Hand zu bearbeiten:

claude mcp add spotify -- npx -y @novalux12/spotify-mcp@latest
# then set SPOTIFY_CLIENT_ID in your shell or MCP env:
export SPOTIFY_CLIENT_ID=your_client_id_here

Oder fügen Sie ihn zu .mcp.json in Ihrem Projektstamm hinzu – gleiche command/args/env-Form wie oben.

Befehl für KI-Agenten

Jeder Coding-Agent (Claude Code, OpenClaw, Cursor, Aider, …) kann den Server in einem einzigen Einfügen installieren, bauen, authentifizieren und registrieren. Geben Sie ihm Ihre Client-ID und lassen Sie ihn laufen:

git clone https://github.com/NovaLux12/spotify-mcp-server.git && cd spotify-mcp-server \
  && npm ci && npm run build \
  && SPOTIFY_CLIENT_ID=your_client_id_here npm run auth

Richten Sie dann die MCP-Konfiguration Ihres Hosts auf <repo>/dist/index.js mit SPOTIFY_CLIENT_ID in seiner Umgebung aus (Formen unten). Agenten sollten abschließend das get_me-Tool einmal aufrufen – es beweist Auth, Scopes und Transport in einem einzigen Round-Trip.

OpenClaw

Fügen Sie zu mcp.servers in ~/.openclaw/openclaw.json hinzu:

"spotify": {
  "command": "node",
  "args": ["/path/to/spotify-mcp-server/dist/index.js"],
  "cwd": "/path/to/spotify-mcp-server",
  "env": { "SPOTIFY_CLIENT_ID": "your_client_id_here" }
}

Starten Sie dann das OpenClaw-Gateway neu, damit es den Server neu startet. Headless-Box? Führen Sie den Auth-Schritt mit SPOTIFY_HEADLESS=1 auf einem beliebigen Rechner mit Browser aus (siehe oben) – Token landen in jedem Fall in ~/.spotify-mcp/tokens.json.

Wenn etwas schiefgeht: Installieren Sie die Doctor-Skill

Dieses Repo enthält skills/spotify-mcp-doctor/SKILL.md – eine prozedurale Diagnose, die Ihr Agent ausführen kann, anstatt dass Sie diese README erneut lesen. Sie geht die realen Fehlermodi der Reihe nach durch: Verkabelung → Binär → App-Anmeldedaten → Token-Frische → Fehlerklassifizierung (Premium vs. Dev-Mode-Allowlist vs. Marktbeschränkung vs. Veraltetes). Installieren:

cp -r skills/spotify-mcp-doctor ~/.openclaw/workspace/skills/   # OpenClaw
# or drop it into .claude/skills/ for Claude Code projects

Fragen Sie dann einfach Ihren Agenten: "Spotify-Tools schlagen fehl – führen Sie die Spotify- Doctor-Skill aus."

Verwendung

Sobald die Verbindung steht, können Sie Claude Dinge fragen wie:

• "Was sind meine Top-Spotify-Titel?"

• "Erstelle eine Playlist mit entspannten Lo-Fi-Songs zum Lernen"

• "Füge den Song Blinding Lights zu meiner Workout-Playlist hinzu"

• "Welche Künstler habe ich in letzter Zeit am meisten gehört?"

• "Mach mir eine Playlist mit einer Late-Night-Fahrstimmung"

Fehlerbehebung

• "Nicht authentifiziert" beim ersten Tool-Aufruf — führen Sie npx -y @novalux12/spotify-mcp@latest auth (oder npm run auth aus einem Klon) aus und schließen Sie den Browser-Flow ab. Token werden unter ~/.spotify-mcp/tokens.json gespeichert und automatisch aktualisiert.

• Redirect-URI stimmt nicht überein — die Redirect-URI der Spotify-App muss exakt http://127.0.0.1:8888/callback sein (ohne abschließenden Schrägstrich). Speichern Sie die App-Einstellungen und versuchen Sie es erneut.

• Port 8888 belegt — ein anderer Prozess hält den Callback-Port; stoppen Sie ihn oder wählen Sie einen freien Port über SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback mit einem anderen Port und passender Dashboard-Einstellung.

• Headless / Docker — setzen Sie SPOTIFY_HEADLESS=1 vor auth; fügen Sie die Redirect-URL zurück ein, wenn Sie dazu aufgefordert werden (siehe oben).

Haftungsausschluss

Dies ist ein persönliches Projekt, das weder mit Spotify verbunden noch von Spotify unterstützt wird. Es wird ohne jegliche Gewährleistung oder Garantie bereitgestellt. Verwenden Sie es verantwortungsbewusst und in Übereinstimmung mit den Spotify-Entwickler-Nutzungsbedingungen. Der Autor ist nicht verantwortlich für Missbrauch oder Folgen, die aus der Nutzung dieser Software entstehen.

Entwicklung

git clone https://github.com/NovaLux12/spotify-mcp-server.git
cd spotify-mcp-server
npm install
npm run build

Kopieren Sie .env.example zu .env und füllen Sie Ihre Client-ID aus, dann:

npm run auth   # authenticate with Spotify
npm run dev    # run from source (no build needed)

Erfordert Node 22.9+ (--env-file-if-exists-Unterstützung). Keine .env-Datei erforderlich – Umgebungsvariablen stammen aus Ihrer Host-Konfiguration oder der Befehlszeile.

Testen

npm test   # node:test runner — unit tests for the client and every tool module, plus an MCP protocol smoke test

Danksagungen

• calebWei/SpotifyMCP — ursprünglicher Auth-Flow und Wiedergabe-Grundgerüst, aus dem dieses Projekt entstanden ist.

• varunneal/spotify-mcp — die Referenzimplementierung, die als Qualitätsmaßstab für Tool-Abdeckung und Ergonomie diente.

Lizenz

MIT © Carme99 und NovaLux12-Mitwirkende.