MCP Claude Spotify

MCP Claude Spotify

Merkmale

• Spotify-Authentifizierung
• Suche nach Titeln, Alben, Künstlern und Playlists
• Wiedergabesteuerung (Wiedergabe, Pause, Weiter, Zurück)
• Erstellen und Verwalten von Wiedergabelisten
• Erhalten Sie personalisierte Empfehlungen
• Zugriff auf die am häufigsten gespielten Titel des Benutzers über verschiedene Zeiträume

Demo

Anforderungen

• Node.js 16 oder höher
• Spotify-Konto
• Claude Desktop
• Spotify-API-Anmeldeinformationen (Client-ID und Client-Geheimnis)

Installation

Installation über Smithery

So installieren Sie MCP Claude Spotify für Claude Desktop automatisch über Smithery :

Manuelle Installation

1. Klonen oder laden Sie dieses Repository herunter:

2. Installieren Sie Abhängigkeiten:

3. Erstellen Sie das Projekt (wenn Sie den Quellcode ändern möchten):

Das Repository enthält bereits vorgefertigte Dateien im build Verzeichnis, sodass Sie Schritt 3 überspringen können, wenn Sie nicht vorhaben, den Quellcode zu ändern.

Einrichten der Spotify-Anmeldeinformationen

Um dieses MCP zu verwenden, müssen Sie die Spotify-API-Anmeldeinformationen abrufen:

1. Gehen Sie zum Spotify Developer Dashboard
2. Melden Sie sich mit Ihrem Spotify-Konto an
3. Klicken Sie auf „App erstellen“
4. Geben Sie Ihre App-Informationen ein:
   • App-Name: „MCP Claude Spotify“ (oder was auch immer Sie bevorzugen)
   • App-Beschreibung: „Spotify-Integration für Claude Desktop“
   • Website: Sie können dieses Feld leer lassen oder eine beliebige URL eingeben.
   • Umleitungs-URI: Wichtig – Fügen Sie http://127.0.0.1:8888/callback hinzu
5. Akzeptieren Sie die Allgemeinen Geschäftsbedingungen und klicken Sie auf „Erstellen“.
6. In Ihrem App-Dashboard sehen Sie die „Client-ID“
7. Klicken Sie auf „Client Secret anzeigen“, um Ihr „Client Secret“ anzuzeigen.

Speichern Sie diese Anmeldeinformationen, da Sie sie für die Konfiguration benötigen.

Ausführen des MCP-Servers

Es gibt zwei Möglichkeiten, den MCP-Server auszuführen:

Option 1: Manuelle Ausführung (empfohlen für die Ersteinrichtung und Fehlerbehebung)

1. Öffnen Sie ein Terminal oder eine Eingabeaufforderung
2. Navigieren Sie zum Projektverzeichnis
3. Führen Sie den Server direkt aus:

Lassen Sie dieses Terminalfenster geöffnet, während Sie Claude Desktop verwenden. Der Server läuft, bis Sie das Terminal schließen.

Option 2: Autostart mit Claude Desktop (empfohlen für den regelmäßigen Gebrauch)

Der Claude Desktop kann den MCP-Server bei Bedarf automatisch starten. So richten Sie dies ein:

Konfiguration

Die Konfigurationsdatei von Claude Desktop befindet sich unter:

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows : %APPDATA%\Claude\claude_desktop_config.json

Bearbeiten Sie diese Datei, um die Spotify MCP-Konfiguration hinzuzufügen. Falls die Datei nicht vorhanden ist, erstellen Sie sie:

Wichtig : Ersetzen:

• ABSOLUTE_PATH_TO_DIRECTORY mit dem vollständigen absoluten Pfad, in dem Sie MCP installiert haben
  • macOS/Linux-Beispiel: /Users/username/mcp-claude-spotify
  • Windows-Beispiel: C:\\Users\\username\\mcp-claude-spotify
• your_client_id_here durch die Client-ID, die Sie von Spotify erhalten haben
• your_client_secret_here durch das Client Secret, das Sie von Spotify erhalten haben

Wenn Sie bereits andere MCPs konfiguriert haben, fügen Sie einfach den Abschnitt „Spotify“ innerhalb des Objekts „mcpServers“ hinzu.

Einrichten von Autostart-Skripten (optional)

Für ein zuverlässigeres Erlebnis können Sie Autostart-Skripte einrichten:

1. Erstellen Sie im Projektverzeichnis eine Datei namens start-spotify-mcp.bat mit folgendem Inhalt:

2. Erstellen Sie eine Verknüpfung zu dieser BAT-Datei
3. Drücken Sie Win+R , geben Sie shell:startup ein und drücken Sie die Eingabetaste
4. Verschieben Sie die Verknüpfung in diesen Ordner, damit er mit Windows gestartet wird
5. Erstellen Sie eine Datei mit dem Namen com.spotify.mcp.plist in ~/Library/LaunchAgents/ mit folgendem Inhalt:

2. Ersetzen Sie den Pfad und die Anmeldeinformationen durch Ihre tatsächlichen Werte
3. Laden Sie den Agenten mit: launchctl load ~/Library/LaunchAgents/com.spotify.mcp.plist
4. Erstellen Sie eine Datei mit dem Namen spotify-mcp.service in ~/.config/systemd/user/ (erstellen Sie das Verzeichnis, falls es nicht existiert):

2. Ersetzen Sie den Pfad und die Anmeldeinformationen durch Ihre tatsächlichen Werte
3. Aktivieren und starten Sie den Dienst:

4. Überprüfen Sie den Status mit:

Verwendung

1. Starten Sie Claude Desktop nach der Änderung der Konfiguration neu
2. Verwenden Sie in Claude den Befehl auth-spotify um den Authentifizierungsprozess zu starten
3. Es öffnet sich ein Browserfenster, in dem Sie die Anwendung autorisieren können
4. Melden Sie sich mit Ihrem Spotify-Konto an und autorisieren Sie die Anwendung
5. Wichtig : Starten Sie Claude Desktop nach erfolgreicher Authentifizierung neu, um die Tool-Registrierung und den WebSocket-Sitzungstoken-Cache des MCP ordnungsgemäß zu initialisieren.
6. Nach dem Neustart sind alle Spotify MCP-Tools ordnungsgemäß registriert und stehen zur Verwendung zur Verfügung

Der MCP-Server läuft als untergeordneter Prozess und wird von Claude Desktop verwaltet. Wenn Claude läuft, startet und verwaltet er automatisch den Node.js-Serverprozess basierend auf der Konfiguration in claude_desktop_config.json .

Verfügbare Tools

Auth-Spotify

Startet den Spotify-Authentifizierungsprozess.

Suche-Spotify

Sucht nach Titeln, Alben, Künstlern oder Wiedergabelisten.

Parameter:

• query : Suchtext
• type : Art der Suche (Titel, Album, Künstler, Playlist)
• limit : Anzahl der Ergebnisse (1-50)

Titel abspielen

Spielt einen bestimmten Titel ab.

Parameter:

• trackId : Spotify-Titel-ID
• deviceId : (Optional) Spotify-Geräte-ID zum Abspielen

Aktuelle Wiedergabe abrufen

Ruft Informationen zur aktuellen Wiedergabe ab.

Pause-Wiedergabe

Pausiert die Wiedergabe.

nächster Titel

Springt zum nächsten Titel.

vorheriger Titel

Kehrt zum vorherigen Titel zurück.

Benutzer-Wiedergabelisten abrufen

Ruft die Wiedergabelisten des Benutzers ab.

Playlist erstellen

Erstellt eine neue Wiedergabeliste.

Parameter:

• name : Name der Wiedergabeliste
• description : (Optional) Beschreibung
• public : (Optional) Ob es öffentlich oder privat ist

Titel zur Playlist hinzufügen

Fügt einer Wiedergabeliste Titel hinzu.

Parameter:

• playlistId : Wiedergabelisten-ID
• trackIds : Array von Track-IDs

Empfehlungen erhalten

Erhält Empfehlungen basierend auf Seeds.

Parameter:

• seedTracks : (Optional) Array von Track-IDs
• seedArtists : (Optional) Array von Künstler-IDs
• seedGenres : (Optional) Array von Genres
• limit : (Optional) Anzahl der Empfehlungen (1-100)

Top-Tracks erhalten

Ruft die am häufigsten gespielten Titel des Benutzers über einen angegebenen Zeitraum ab.

Parameter:

• limit : (Optional) Anzahl der zurückzugebenden Titel (1-50, Standard: 20)
• offset : (Optional) Index des ersten zurückzugebenden Titels (Standard: 0)
• time_range : (Optional) Zeitrahmen für die Berechnung der Affinität:
  • short_term : Ungefähr die letzten 4 Wochen
  • medium_term : Ungefähr die letzten 6 Monate (Standard)
  • long_term : Daten mehrerer Jahre

Fehlerbehebung

Fehler „Server getrennt“

Wenn in Claude Desktop der Fehler „MCP Spotify: Server getrennt“ angezeigt wird:

1. Überprüfen Sie, ob der Server läuft :
   • Öffnen Sie ein Terminal und führen Sie node build/index.js manuell aus dem Projektverzeichnis aus
   • Wenn der Server erfolgreich startet, verwenden Sie Claude, während Sie dieses Terminal geöffnet halten
2. Überprüfen Sie Ihre Konfiguration :
   • Stellen Sie sicher, dass der absolute Pfad in claude_desktop_config.json für Ihr System korrekt ist
   • Überprüfen Sie noch einmal, ob Sie doppelte Backslashes ( \\ ) für Windows-Pfade verwendet haben
   • Stellen Sie sicher, dass Sie den vollständigen Pfad vom Stammverzeichnis Ihres Dateisystems verwenden.
3. Probieren Sie die Autostart-Option :
   • Richten Sie das Autostart-Skript für Ihr Betriebssystem ein, wie im Abschnitt „Einrichten von Autostart-Skripten“ beschrieben.
   • Dadurch wird sichergestellt, dass der Server immer läuft, wenn Sie ihn brauchen

Browser öffnet sich nicht automatisch

Wenn der Browser während der Authentifizierung nicht automatisch geöffnet wird, besuchen Sie manuell: http://127.0.0.1:8888/login

Authentifizierungsfehler

Stellen Sie sicher, dass Sie die Umleitungs-URI in Ihrem Spotify-Entwickler-Dashboard korrekt konfiguriert haben: http://127.0.0.1:8888/callback

Server-Startfehler

Überprüfen Sie Folgendes:

• Umgebungsvariablen sind in Ihrer claude_desktop_config.json oder Ihrem Startskript korrekt konfiguriert
• Node.js ist installiert und kompatibel (v16+)
• Erforderliche Ports (8888) sind verfügbar und nicht durch die Firewall blockiert
• Sie haben die Berechtigung, das Skript am angegebenen Speicherort auszuführen

Werkzeuge, die in Claude nicht erscheinen

Wenn die Spotify-Tools nach der Authentifizierung nicht in Claude angezeigt werden:

• Stellen Sie sicher, dass Sie Claude Desktop nach erfolgreicher Authentifizierung neu gestartet haben
• Überprüfen Sie die Claude Desktop-Protokolle auf MCP-Kommunikationsfehler
• Stellen Sie sicher, dass der MCP-Serverprozess ausgeführt wird (führen Sie ihn zur Bestätigung manuell aus).
• Überprüfen Sie, ob der MCP-Server korrekt in der Claude Desktop MCP-Registrierung registriert ist

Überprüfen, ob der Server läuft

So überprüfen Sie, ob der Server läuft:

• Windows : Öffnen Sie den Task-Manager, gehen Sie zur Registerkarte „Details“ und suchen Sie nach „node.exe“.
• macOS/Linux : Öffnen Sie das Terminal und führen Sie ps aux | grep node aus.

Wenn der Server nicht ausgeführt wird, starten Sie ihn manuell oder verwenden Sie die Autostart-Methode.

Testen

Dieses Projekt umfasst automatisierte Tests zur Sicherstellung der Codequalität und Funktionalität. Die Testsuite verwendet Jest mit TypeScript-Unterstützung und umfasst:

• Zod-Schemavalidierung – überprüft alle Eingabeschemata und validiert die Daten korrekt
• Spotify-API-Interaktionen – testet die API-Anforderungsverarbeitung und Fehlerbehandlung
• MCP-Serverfunktionalität – gewährleistet die ordnungsgemäße Registrierung und Ausführung von Tools

Ausführen von Tests

Stellen Sie zunächst sicher, dass alle Entwicklungsabhängigkeiten installiert sind:

So führen Sie alle Tests aus:

So führen Sie eine bestimmte Testdatei aus:

Wenn Probleme mit ESM-Modulen auftreten, stellen Sie sicher, dass Sie Node.js v16 oder höher verwenden und dass die Umgebungsvariable NODE_OPTIONS das Flag --experimental-vm-modules enthält, wie in package.json konfiguriert.

Teststruktur

• tests/schemas.test.ts : Tests für Eingabevalidierungsschemata
• tests/spotify-api.test.ts : Tests für Spotify-API-Interaktionen
• tests/server.test.ts : Tests für die MCP-Serverfunktionalität

Neue Tests hinzufügen

Wenn Sie neue Funktionen hinzufügen, schließen Sie bitte entsprechende Tests ein:

1. Für neue Schemata fügen Sie Validierungstests in schemas.test.ts hinzu
2. Für Spotify-API-Funktionen fügen Sie Tests in spotify-api.test.ts
3. Für MCP-Tools fügen Sie Tests in server.test.ts hinzu

Alle Tests sollten mit Jest und dem ESM-Modulformat mit TypeScript geschrieben werden.

Sicherheitshinweise

• Geben Sie niemals Ihre Client-ID und Ihr Client-Geheimnis weiter
• Das Zugriffstoken wird jetzt im Home-Verzeichnis des Benutzers unter ~/.spotify-mcp/tokens.json gespeichert, um die Persistenz zwischen Sitzungen und mehreren Instanzen zu ermöglichen
• Es werden keine Benutzerdaten auf der Festplatte gespeichert

Widerrufen des Anwendungszugriffs

Aus Sicherheitsgründen möchten Sie möglicherweise den Zugriff der Anwendung auf Ihr Spotify-Konto widerrufen, wenn:

• Sie verwenden diese Integration nicht mehr
• Sie vermuten einen unberechtigten Zugriff
• Sie beheben Authentifizierungsprobleme

So widerrufen Sie den Zugriff:

1. Gehen Sie zu Ihrer Spotify-Kontoseite
2. Navigieren Sie im Menü zu „Apps“
3. Suchen Sie nach „MCP Claude Spotify“ (oder dem Namen, den Sie für Ihre App gewählt haben).
4. Klicken Sie auf „ZUGRIFF ENTFERNEN“

Dadurch werden alle Zugriffs- und Aktualisierungstoken sofort ungültig. Wenn Sie den Befehl auth-spotify das nächste Mal verwenden, müssen Sie die Anwendung erneut autorisieren.

Beitragen

Beiträge sind willkommen! Hier sind einige Richtlinien:

Entwicklungs-Workflow

1. Forken Sie das Repository
2. Erstellen Sie einen Feature-Zweig ( git checkout -b feature/amazing-feature )
3. Nehmen Sie Ihre Änderungen vor
4. Führen Sie Tests durch, um sicherzustellen, dass sie erfolgreich sind ( npm test )
5. Übernehmen Sie Ihre Änderungen ( git commit -m 'Add some amazing feature' )
6. Pushen zum Zweig ( git push origin feature/amazing-feature )
7. Öffnen einer Pull-Anfrage

Richtlinien für den Codestil

Dieses Projekt folgt diesen Codierungsstandards:

• Verwenden Sie TypeScript mit strenger Typprüfung
• Folgen Sie dem ESM-Modulformat
• Verwenden Sie 2 Leerzeichen für die Einrückung
• Verwenden Sie camelCase für Variablen und Funktionen
• Verwenden Sie PascalCase für Klassen und Schnittstellen
• Dokumentfunktionen mit JSDoc-Kommentaren
• Halten Sie die Zeilenlänge unter 100 Zeichen

Projektstruktur

Das Projekt folgt dieser Struktur:

Pull Request-Prozess

1. Stellen Sie sicher, dass Ihr Code den Stilrichtlinien entspricht
2. Aktualisieren Sie die Dokumentation bei Bedarf
3. Fügen Sie Tests für neue Funktionen hinzu
4. Stellen Sie sicher, dass alle Tests erfolgreich sind
5. Ihr PR wird von Betreuern überprüft

Weiterführende Links

• Modellkontextprotokoll
• Spotify Web API-Dokumentation
• Claude Desktop
• MCP-Serie

Lizenz

Dieses Projekt ist unter der Mozilla Public License 2.0 lizenziert – Einzelheiten finden Sie in der Datei LICENSE .