Navidrome MCP Server

Ein MCP-Server (Model Context Protocol) für Navidrome. Claude Desktop, Claude Code, Cursor und andere MCP-Clients können Ihre Bibliothek durchsuchen, Wiedergabelisten erstellen, neue Musik entdecken und Audio über die Lautsprecher Ihres Computers abspielen.

Inhaltsverzeichnis

• Funktionen

• Verfügbare Tools

• Installation & Einrichtung

• Fehlerbehebung

• Entwicklung

• Lizenz

• Support

Related MCP server: Spotify MCP Server

Funktionen

🎵 Musikbibliothek

Durchsuchen und suchen Sie Songs, Alben, Künstler, Genres und Tags. Filter decken Abfrage, Sternstatus, Jahresbereich, Sortierreihenfolge und Tag-Werte ab, und sie kombinieren: „alle meine markierten Jazz-Alben aus den 90ern, sortiert nach Jahr“ oder „jeder Song mit dem Tag Soundtrack und einer 5-Sterne-Bewertung“. Tag-Analyse-Tools zeigen, was in Ihrer Bibliothek ist, sodass Sie nicht über Filterwerte raten müssen.

🔊 Lokale Audio-Wiedergabe

Erfordert mpv auf dem Host, auf dem der MCP-Server läuft (siehe mpv installieren).

Audio wird über die Lautsprecher Ihres Computers abgespielt, ohne Browser oder Navidrome-Weboberfläche. Suchen und abspielen in einem Schritt: „spiele 5 zufällige markierte Alben ab“, „stelle alles, was ich aus den 90ern markiert habe, sortiert nach Jahr, in die Warteschlange“ oder „füge 10 zufällige Rocksongs zu dem hinzu, was gerade läuft, gemischt“. Alben haben drei Mischmodi: Reihenfolge beibehalten, Albumreihenfolge zufällig oder Titel verschachteln.

Die Warteschlange ist während der Wiedergabe bearbeitbar: neu anordnen oder mischen, ohne den aktuellen Song zu unterbrechen, und das Entfernen des aktuellen Titels rückt zum nächsten vor. Gespeicherte Navidrome-Radiostationen (Icecast, SHOUTcast) streamen über mpv mit Live-ICY-Metadaten, sodass Sie sehen können, was der Sender spielt. Wiedergaben werden zurück an Navidrome gescrobbelt, sodass Abspielzahlen und letzte Aktivitäten synchron bleiben. mpv startet bei der ersten Verwendung, kann Neustarts von MCP-Clients über einen benutzerspezifischen Socket überleben (siehe MPV Remote-Einrichtung für die Lebensdauerregeln) und funktioniert unter Linux, macOS und Windows 11.

Dies funktioniert mit Sprach-Transports (Whisper STT + TTS) für ein freihändiges Musikgerät auf einem Raspberry Pi oder einem ständig laufenden Computer.

🎛️ MPV Remote (Web-UI)

Erfordert mpv (wie bei lokaler Audio-Wiedergabe). Standardmäßig aktiviert und startet mit dem Server.

Eine Weboberfläche unter http://localhost:8808 gibt jedem Browser die lokalen Wiedergabesteuerungen: aktuell läuft mit Cover-Art, Transport und Suche, Lautstärke und eine Live-Warteschlange, die Sie anklicken können, um zu springen, in Echtzeit aktualisiert. Ein integrierter Auswähler startet jede Wiedergabeliste, Ihre markierten Songs oder Ihre markierten Alben von der Seite, sodass es als Fernbedienung ohne den Assistenten funktioniert. Aktivieren Sie Im LAN freigeben, um die Wiedergabe von einem Telefon oder Tablet zu steuern. Audio kommt immer aus dem Computer, auf dem der Server läuft. Einrichtung, Lebensdauer und Sicherheitsdetails finden Sie in MPV Remote-Einrichtung.

🎶 Wiedergabelisten

Erstellen, aktualisieren, neu anordnen und löschen Sie Wiedergabelisten. Fügen Sie Songs, ganze Alben, Künstler-Diskografien oder bestimmte Discs in einem Vorgang hinzu. Finden Sie heraus, welche Wiedergabelisten einen bestimmten Song enthalten. Erstellen Sie Wiedergabelisten aus Hördaten: „eine ‚Hidden Gems‘-Wiedergabeliste mit 5-Sterne-Songs mit unter 5 Abspielungen“ oder „einen Top-Track von jedem Album meiner Top-10-Künstler, in chronologischer Reihenfolge“.

🎼 Musikentdeckung (Last.fm)

Erfordert einen Last.fm-API-Schlüssel (kostenlos unter last.fm/api), der auf der Einstellungsseite festgelegt wird.

Finden Sie ähnliche Künstler und Titel, rufen Sie Biografien und Top-Tracks ab und durchsuchen Sie globale Musik-Charts. Kombinieren Sie dies mit Ihrer Bibliothek, um fehlende Alben zu finden („Alben, die in meinen Top-5-Künstlern fehlen, nach Beliebtheit sortiert“), übersehene Musik wiederzuentdecken („Titel, die meinen Favoriten ähneln, die ich besitze, aber nie spiele“) oder „Best Of“-Wiedergabelisten aus dem zu erstellen, was Sie besitzen.

🎤 Synchronisierte Liedtexte

In der Einstellungsseite aktiviert (LRCLIB-Anbieter + ein User-Agent). Kein API-Schlüssel erforderlich.

Rufen Sie zeitlich synchronisierte Liedtexte (LRC-Format, Millisekunden-Zeitstempel) aus der Community-Datenbank von LRCLIB ab, abgeglichen nach Titel, Künstler, Album und Dauer. Klartext wird zurückgegeben, wenn keine synchronisierte Version existiert.

📻 Internetradio

Verwalten Sie Navidrome-Radiostationen und entdecken Sie weltweit neue. Stream-URLs werden validiert, bevor sie hinzugefügt werden (MP3-, AAC-, OGG- und FLAC-Erkennung), und SHOUTcast/Icecast-Metadaten werden extrahiert. Massenwartung funktioniert: „validiere alle meine Stationen und entferne die defekten“ oder „teste diese 10 URLs und füge die funktionierenden hinzu“.

Die globale Entdeckung verwendet Radio Browser (erfordert einen User-Agent, der auf der Einstellungsseite festgelegt wird). Es deckt Tausende von Stationen mit Filtern für Genre, Land, Sprache, Codec, Bitrate und Beliebtheit ab. Stimmen und Klicks werden registriert, sodass Ihre Nutzung das Community-Ranking speist.

📊 Höranalysen

Zugriff auf Abspielzahlen, letzte Aktivitäten, Top-bewertete und meistgespielte Auflistungen sowie die Tag-Verteilung in Ihrer Bibliothek. Verwenden Sie dies, um Gewohnheiten zu vergleichen („Genres, die ich dieses Jahr mehr vs. weniger spiele“), vergessene Favoriten und One-Hit-Wonder zu finden oder Stimmungs-Wiedergabelisten aus Ihren Hörgewohnheiten zu erstellen.

⭐ Bewertungen & Favoriten

Markieren und entfernen Sie Sterne für Songs, Alben und Künstler. Legen Sie 0-5-Sterne-Bewertungen fest und listen Sie alles Markierte oder Top-bewertete auf. Lesen und schreiben Sie die gespeicherte Navidrome-Warteschlange, die die Weboberfläche für die geräteübergreifende Synchronisierung verwendet.

📚 Multi-Bibliotheks-Unterstützung

Filtern Sie alle Vorgänge auf eine Teilmenge Ihrer Navidrome-Bibliotheken. Legen Sie einen Standard in der Einstellungsseite fest (Standardbibliotheken, library.defaultLibraryIds) oder wechseln Sie die aktiven Bibliotheken zur Laufzeit.

Verfügbare Tools

Tool-Kategorien, deren Überschrift erfordert ... sagt, werden nur registriert, wenn diese Konfiguration vorhanden ist.

Kernsystem

Bibliotheksverwaltung

Suche

Wiedergabelisten

Bewertungen & Favoriten

Hörverlauf & gespeicherte Warteschlange

Metadaten & Tags

Last.fm-Entdeckung (erfordert einen Last.fm-API-Schlüssel)

Liedtexte (erfordert den LRCLIB-Anbieter, in der Einstellungsseite festgelegt)

Radio-Verwaltung

Globale Radiosuche (erfordert einen Radio-Browser-User-Agent)

Lokale Wiedergabe (erfordert mpv)

Die Wiedergabe streamt standardmäßig die Originaldatei (siehe Transcode-Format unter Erstkonfiguration).

Installation & Einrichtung

Voraussetzungen

• Node.js 20+ (Download)

• Ein laufender Navidrome-Server

• Ein MCP-kompatibler Client (Claude Desktop, Claude Code, Cursor oder ein anderer MCP-Client mit lokaler stdio-Unterstützung)

• Optional: mpv für lokale Audiowiedergabe

Schnelleinrichtung

Das veröffentlichte Paket installieren (aktualisiert sich beim Start automatisch):

npm install -g navidrome-mcp

Paket: navidrome-mcp auf npm.

Für einen Entwicklungs-Build:

git clone https://github.com/Blakeem/Navidrome-MCP.git
cd Navidrome-MCP
pnpm install
pnpm build

MCP-Client konfigurieren

Die MCP-Client-Konfiguration teilt dem Client nur mit, wie der Server gestartet wird. Ihre Navidrome-Anmeldedaten und alle Optionen befinden sich in einer lokalen settings.json, die über eine Browser-Einstellungsseite bearbeitet wird, sodass keine Geheimnisse in der Client-JSON oder der Umgebung landen. Die Einstellungsseite öffnet sich beim ersten Start (siehe Erstkonfiguration).

Für Claude Desktop bearbeiten Sie claude_desktop_config.json (Speicherorte: %APPDATA%/Claude/ unter Windows, ~/Library/Application Support/Claude/ unter macOS, ~/.config/Claude/ unter Linux). Andere MCP-Clients verwenden dieselbe JSON-Struktur.

{
  "mcpServers": {
    "navidrome": {
      "command": "npx",
      "args": ["navidrome-mcp"]
    }
  }
}

Für einen manuellen Build ersetzen Sie command/args durch:

"command": "node",
"args": ["/absolute/path/to/Navidrome-MCP/dist/index.js"]

Erstkonfiguration

Beim ersten Start ohne Konfiguration öffnet sich die Einstellungsseite in Ihrem Browser. Dies geschieht unabhängig davon, ob Sie den MCP-Server oder den eigenständigen Web-Player (navidrome-web) gestartet haben. Wenn kein Browser geöffnet werden kann (z. B. über SSH), wird die URL in der Konsole ausgegeben, und der nicht konfigurierte MCP-Server stellt ein open_settings-Tool bereit, das sie zurückgibt. Öffnen Sie die Einstellungsseite jederzeit mit:

npx navidrome-config

Geben Sie Ihre Navidrome-URL, Ihren Benutzernamen und Ihr Passwort sowie optionale Funktionen ein. Klicken Sie dann auf Verbindung testen und Speichern. Dadurch wird eine lokale settings.json geschrieben (Struktur: settings.example.json). Die Einstellungen werden beim Start geladen und nicht heiß neu geladen. Starten Sie daher das von Ihnen Gestartete neu: Beenden Sie den MCP-Client und öffnen Sie ihn erneut, oder führen Sie navidrome-web erneut aus. Beim Upgrade von der alten Env-Einrichtung wird das Formular mit Ihren vorherigen env/.env-Werten vorausgefüllt. Überprüfen und speichern Sie.

Headless-Maschinen und Container: Die Einstellungsseite bindet nur an Loopback. Ein Host ohne Browser (ein VPS, ein Docker-Container) wird daher stattdessen mit Umgebungsvariablen konfiguriert. Wenn keine settings.json existiert, läuft der Server mit NAVIDROME_URL, NAVIDROME_USERNAME und NAVIDROME_PASSWORD sowie optionalen Variablen wie MCP_TRANSPORT und LASTFM_API_KEY. Eine einmal erstellte settings.json hat immer Vorrang vor der Umgebung.

Erforderlich: Navidrome-URL, Benutzername, Passwort.

Optional (in der Einstellungsseite festlegen):

• Standard-Bibliotheken: Kommagetrennte Bibliotheks-IDs, die standardmäßig aktiviert werden. Leer bedeutet alle.

• Last.fm-API-Schlüssel: Aktiviert die Last.fm-Entdeckung.

• Radio-Browser-User-Agent: Aktiviert die globale Sendersuche.

• Lyrics-Anbieter (LRCLIB) + User-Agent: Aktiviert das Abrufen von Liedtexten.

• mpv-Pfad: Der Speicherort der mpv-Binärdatei, falls sie nicht im PATH liegt. Leer lässt automatisch erkennen.

• Transcode-Format: Standardmäßig raw, das die Originaldatei für beste Qualität und zuverlässiges Spulen streamt. Legen Sie einen Codec fest (z. B. mp3, opus) für langsame oder datenlimitierte Verbindungen. Die Bitrate gilt nur, wenn ein Codec festgelegt ist.

• Web-UI (Port / Host / Freigabe / aktiviert / Browser automatisch öffnen): Konfiguriert die MPV-Fernbedienung (siehe MPV-Fernbedienung einrichten). Standardmäßig localhost:8808.

• Transport (Typ / Host / Port): Legt fest, wie der Server das MCP-Protokoll bereitstellt. Standardmäßig stdio, der lokale Transport, den Desktop-Clients verwenden. Setzen Sie type auf http, um den Server als Netzwerkprozess auszuführen (siehe Über HTTP ausführen).

Funktionen werden aktiviert, wenn ihre Einstellungen vorhanden sind.

mpv installieren (optional)

mpv ist ein plattformübergreifender Media-Player. Der Server registriert die Wiedergabe-Tools, wenn er mpv beim Start erkennt. Ohne mpv verwaltet der Server weiterhin Ihre Bibliothek und die gespeicherte Navidrome-Warteschlange, erzeugt aber keinen Ton.

macOS (über Homebrew):

brew install mpv

Linux:

sudo apt install mpv       # Debian / Ubuntu / Mint / PopOS
sudo dnf install mpv       # Fedora / RHEL / CentOS Stream
sudo pacman -S mpv         # Arch / Manjaro
sudo zypper install mpv    # openSUSE

Windows:

winget install shinchiro.mpv   # winget is included on Windows 11
scoop install mpv
choco install mpv

Verwenden Sie die vollständige ID shinchiro.mpv. Ein einfaches winget install mpv fordert Sie auf, zwischen diesem und einem inoffiziellen Store-Paket zu wählen. Der shinchiro-Build ist der, den mpv.io für Windows verlinkt.

Hinweis zum Windows-PATH. Das Paket shinchiro.mpv installiert nach C:\Program Files\MPV Player\ und fügt sich **nicht** selbst zum PATH hinzu. Entweder:

• Fügen Sie diesen Ordner zu Ihrem PATH hinzu (Systemeigenschaften → Umgebungsvariablen → Pfad → Neu) und öffnen Sie dann ein neues Terminal, oder

• Legen Sie den mpv-Pfad in der Einstellungsseite (playback.mpvPath) auf den vollständigen mpv.exe-Pfad fest, z. B. C:\Program Files\MPV Player\mpv.exe.

Andere Installationsmethoden (scoop, choco, manuelles ZIP) verwenden andere Ordner. Wenn mpv --version in einem neuen Terminal fehlschlägt, suchen Sie mpv.exe und wenden Sie eine der obigen Korrekturen an.

Eine vorgefertigte Binärdatei von mpv.io funktioniert ebenfalls. Überprüfen Sie mit mpv --version. Starten Sie dann Ihren MCP-Client neu, damit der Server mpv erneut erkennt.

MPV-Fernbedienung einrichten

Aktivierung & Lebensdauer

Das Bedienfeld ist standardmäßig aktiviert. Der Server startet es als separaten navidrome-web-Prozess, und der Port bindet sofort, sodass die Seite erreichbar ist, bevor etwas abgespielt wird. Hosts ohne mpv starten es nicht. Die Player-Einstellungen befinden sich hinter dem Zahnrad-Symbol im Player, und die Zahnrad- und Ein/Aus-Tasten erscheinen nur für Browser auf dem Host-Rechner.

Ob die Wiedergabe das Schließen Ihres KI-Clients überlebt:

• Standard (aus): Der vom MCP gestartete Player und mpv stoppen, wenn der MCP-Server geschlossen oder neu gestartet wird.

• Nach dem Schließen des MCP-Servers weiter abspielen (webui.persistAfterMcpExit, in der Einstellungsseite oder im Zahnrad-Dialog): Der Player läuft weiter. Stoppen Sie ihn mit der Ein/Aus-Taste.

• Selbst gestartet (navidrome-web, unten): Läuft immer unabhängig. Der MCP-Server verbindet sich damit und fährt ihn nie herunter.

mpv stoppt, wenn der Player stoppt, ohne Hintergrund-Leerlauf-Timeout. Um das Bedienfeld zu deaktivieren, deaktivieren Sie Begleitendes Bedienfeld aktivieren in der Einstellungsseite (webui.enabled).

Eigenständig ausführen

Führen Sie den Player unabhängig von einem MCP-Client aus:

navidrome-web                # after: npm install -g navidrome-mcp
# or, from a dev clone / manual build:
node dist/web/main.js

Er liest settings.json, öffnet Ihren Browser und läuft im Hintergrund, bis Sie ihn mit der Ein/Aus-Taste stoppen. Er koexistiert mit einer vom MCP gestarteten Instanz: Der Prozess, der den Port zuerst bindet, besitzt ihn, und der andere verbindet sich. Protokolle gehen an navidrome-web.log in Ihrem Konfigurationsverzeichnis.

Wenn noch nichts konfiguriert ist, öffnet der Start die Einstellungsseite anstelle des Players (siehe Erstkonfiguration). Füllen Sie sie aus und speichern Sie. Starten Sie dann navidrome-web erneut.

Desktop-Verknüpfung (empfohlen)

Erzeugt ein doppelklickbares Symbol für Ihre Plattform. Es startet den Player im Hintergrund ohne Terminalfenster und öffnet Ihren Browser. Wenn bereits ein Player läuft, wird nur der Browser geöffnet.

navidrome-web-shortcut       # after: npm install -g navidrome-mcp
# or, from a dev clone (see Development):
pnpm make:launcher

Die Verknüpfung speichert die absoluten Pfade zu Ihrem node und dem erstellten Player, sodass sie ohne etwas auf PATH funktioniert. Sie schreibt:

• Linux: Navidrome Player.desktop auf Ihrem Desktop und in Ihrem Anwendungsmenü (~/.local/share/applications). Unter GNOME: Rechtsklick → Starten erlauben beim ersten Mal.

• macOS: Navidrome Player.app auf Ihrem Desktop (ziehen Sie es bei Bedarf in /Applications).

• Windows: Navidrome Player.vbs auf Ihrem Desktop und im Startmenü. (Ein OneDrive-umgeleiteter Desktop legt es dort ab.)

Führen Sie den Generator erneut aus, nachdem Sie das Projekt verschoben oder neu erstellt haben, um die Pfade zu aktualisieren.

Konfiguration

Alle Einstellungen sind optional und befinden sich im Abschnitt Web-UI der Einstellungsseite, unten nach ihren settings.json-Pfaden aufgeschlüsselt. Starten Sie den Client nach dem Speichern neu. Die Ausnahme ist persistAfterMcpExit, das das Zahnrad-Modal live anwendet.

Verwendung als Telefon-/Tablet-Fernbedienung

1. Aktivieren Sie Im LAN verfügbar machen auf der Einstellungsseite und speichern Sie.

2. Starten Sie den MCP-Client neu (oder starten Sie navidrome-web neu).

3. Der Player protokolliert die LAN-URLs, unter denen er beim Binden erreichbar ist (z. B. http://192.168.1.42:8808). Öffnen Sie eine davon im Browser Ihres Telefons und setzen Sie ein Lesezeichen.

Sicherheitshinweis

Die Weboberfläche hat keine Authentifizierung. Jeder, der den Port erreichen kann, kann pausieren, überspringen, suchen, die Lautstärke ändern und in der Warteschlange springen.

• Mit webui.host=127.0.0.1 (Standard) ist sie nur vom Host-Rechner aus erreichbar, was sicher ist.

• Mit Im LAN verfügbar machen (webui.expose=true) ist sie von allem im LAN erreichbar. Das ist in einem vertrauenswürdigen Heimnetzwerk in Ordnung, aber setzen Sie sie nicht dem öffentlichen Internet aus. Es gibt keine Ratenbegrenzung, und die Steuerungs-API erlaubt Warteschlangenänderungen und das Starten von Wiedergabelisten. Die Playereinstellungen und der Netzschalter bleiben nur auf Loopback beschränkt und sind für entfernte Browser ausgeblendet, sodass ein Telefon in Ihrem LAN die Wiedergabe steuern, aber keine Einstellungen ändern oder den Player herunterfahren kann. Die Haupt-Einstellungsseite wird nie verfügbar gemacht. Nach der Freigabe gibt GET /healthz außerhalb des Hosts 404 zurück, um ein Versions-Fingerprinting zu vermeiden. Überprüfen Sie die Gesundheit des Players daher von seinem Host aus.

Ausführung über HTTP

Standardmäßig spricht der Server MCP über stdio. Der Client startet ihn als untergeordneten Prozess und kommuniziert über stdin/stdout. Das funktioniert für einen Desktop-Client auf derselben Maschine, ist aber nicht über ein Netzwerk erreichbar.

Wenn Sie den Transport auf http setzen, bindet der Server einen Socket und stellt den MCP Streamable HTTP transport unter /mcp bereit. Er läuft dann als eigenständiger Prozess, mit dem vernetzte MCP-Clients direkt verbunden werden, ohne supergateway- oder mcp-proxy-Brücke.

Fügen Sie einen transport-Block zu Ihrer settings.json hinzu. host ist standardmäßig 127.0.0.1 (nur Loopback). Setzen Sie expose: true, um alle Schnittstellen (0.0.0.0) zu binden, damit ein entfernter Client sie erreichen kann. Ein explizites host überschreibt expose. Setzen Sie authToken, um eine Bearer-Authentifizierung zu verlangen. Dies wird empfohlen, wenn der Port über Loopback hinaus erreichbar ist, und die Einstellungsseite hat dafür eine Generieren-Schaltfläche:

"transport": {
  "type": "http",
  "port": 3000,
  "expose": true,
  "authToken": "a-long-random-secret"
}

Richten Sie einen HTTP-fähigen MCP-Client auf http://<host>:<port>/mcp aus:

{
  "mcpServers": {
    "navidrome": {
      "type": "http",
      "url": "http://your-host:3000/mcp",
      "headers": { "Authorization": "Bearer a-long-random-secret" }
    }
  }
}

Wenn ein Token gesetzt ist, muss jede /mcp-Anfrage Authorization: Bearer <token> enthalten (in konstanter Zeit verglichen), und alles andere erhält eine 401. Wenn der Transport eine Nicht-Loopback-Adresse ohne Token bindet, protokolliert der Server beim Start eine Warnung, anstatt den Start zu verweigern, sodass eine durch eine Firewall oder NetworkPolicy abgesicherte Bereitstellung weiterhin läuft. GET /healthz ist nie abgeschirmt. Es ist ein nicht authentifizierter Liveness-Endpunkt für Container-Health-Checks, gibt 200 {"status":"ok"} zurück und führt keinen Navidrome-Aufruf durch.

Host-Filterung (DNS-Rebinding-Schutz): Bei der Standardbindung (Loopback ohne Auth-Token) werden Anfragen, deren Host-Header kein Loopback-Alias ist, abgelehnt, sodass eine bösartige Webseite den Server nicht über Ihren Browser steuern kann. Das Setzen eines authToken oder das Binden einer Nicht-Loopback-Adresse deaktiviert den automatischen Filter. Eine entfernte Bereitstellung wird über Namen erreicht, die der Server nicht im Voraus kennen kann, und das Bearer-Token blockiert bereits Rebinding (ein gelockter Browser kann Ihr Token nicht anhängen). Um die akzeptierten Namen festzulegen, setzen Sie transport.allowedHosts, das immer durchgesetzt wird, wenn es vorhanden ist. Setzen Sie transport.allowedOrigins nur für Browser-Clients. Es prüft den Origin-Header.

Der Transport kann auch über Umgebungsvariablen konfiguriert werden: MCP_TRANSPORT (stdio|http), MCP_HTTP_HOST, MCP_HTTP_PORT, MCP_HTTP_EXPOSE (true zum Binden aller Schnittstellen), MCP_HTTP_AUTH_TOKEN und MCP_HTTP_ALLOWED_HOSTS / MCP_HTTP_ALLOWED_ORIGINS (durch Kommas getrennt). Die Weboberfläche hat eine passende WEBUI_*-Familie (WEBUI_ENABLED, WEBUI_PORT, WEBUI_HOST, WEBUI_EXPOSE, WEBUI_AUTO_OPEN_BROWSER, WEBUI_PERSIST_AFTER_MCP_EXIT). Diese gelten, wenn keine settings.json existiert, und füllen das Einstellungsformular beim ersten Start vor (siehe Erstkonfiguration).

Ein Konto, gemeinsamer Zustand: Jede HTTP-Sitzung wird von einem Prozess bedient, der ein authentifiziertes Navidrome-Konto hält, und die Auswahl der aktiven Bibliothek ist prozessglobal. Ein set_active_libraries-Aufruf ändert den Bibliotheksfilter für alle verbundenen Sitzungen, und get_user_details spiegelt diese gemeinsame Auswahl wider.

Sicherheit: Der Server hält eine authentifizierte Navidrome-Sitzung, sodass ein offener Port die volle Kontrolle über die Bibliothek ohne Anmeldedaten bedeutet. Das Freigeben des Ports über localhost hinaus ist eine Opt-in-Entscheidung (expose: true oder ein explizites Nicht-Loopback-host). Wenn Sie dies tun, setzen Sie ein Auth-Token oder beschränken Sie den Zugriff mit einer Firewall, einer Kubernetes-NetworkPolicy oder einem Reverse-Proxy, der TLS hinzufügt. Behalten Sie den Standard-stdio-Transport bei, es sei denn, Sie benötigen Fernzugriff.

Wo der Ton ausgegeben wird. Der Transport entscheidet, wer das MCP-Protokoll erreichen kann, und bewegt das Audio nicht. mpv läuft neben dem Serverprozess, sodass der Rechner, auf dem der Server läuft, den Ton erzeugt. HTTP auf einem Rechner außerhalb eines Containers bietet Fern-MCP-Zugriff mit funktionierender Wiedergabe: Führen Sie den Server auf dem Rechner aus, der mit Ihren Lautsprechern verbunden ist, richten Sie entfernte Clients auf http://that-machine:3000/mcp aus und setzen Sie ein authToken. Ein Container bietet einen ständig verfügbaren Endpunkt nur für die Bibliothekstools (Suche, Wiedergabelisten, Bewertungen, Radio-Metadaten, Last.fm, Liedtexte) ohne Audio.

Für Container siehe Ausführung in Docker: das Image, Bereitstellungsformen, eingebundene Konfiguration und Audio-Hinweise.

Ein Hinweis zu ChatGPT Desktop

ChatGPTs MCP-Unterstützung (Web und Desktop) erfordert einen gehosteten HTTPS-Endpunkt und funktioniert nicht mit lokalen stdio-Servern. Dieser Server kann MCP über HTTP bereitstellen (siehe Ausführung über HTTP), sodass Sie ihn hinter einem Reverse-Proxy hosten können, der TLS beendet, anstatt einer Brücke wie mcp-remote. Für einen selbst gehosteten Musikserver ist es einfacher, Claude Desktop, Claude Code, Cursor oder einen anderen Client mit stdio-Unterstützung zu verwenden.

Fehlerbehebung

Verbindungsprobleme

• Stellen Sie sicher, dass Navidrome läuft und erreichbar ist

• Stellen Sie sicher, dass die Navidrome-URL auf der Einstellungsseite das Protokoll enthält (http:// oder https://)

• Verwenden Sie die Schaltfläche Verbindung testen auf der Einstellungsseite (oder testen Sie die Anmeldedaten mit curl / einem Browser), bevor Sie speichern

macOS-spezifisch

• Siehe den macOS-Fehlerbehebungsleitfaden. Das häufige Problem ist ein nicht gefundener Node.js-Pfad, der mit symbolischen Links oder vollständigen Pfaden behoben wird.

Konfiguration

• Verwenden Sie absolute Pfade in Konfigurationsdateien

• Validieren Sie JSON (keine nachgestellten Kommas)

• Starten Sie Ihren MCP-Client nach Änderungen neu

Bekannte Einschränkungen

• Kein Audio ohne mpv. Verwenden Sie stattdessen die Navidrome-Weboberfläche oder einen Subsonic-Client (siehe mpv installieren).

• Zuletzt gespielt hat keine Zeitstempel. Navidrome stellt Wiedergabezähler und Abschlussstatus bereit, nicht wann ein Titel zuletzt gespielt wurde.

• Gespeicherte Warteschlange ≠ Live-Warteschlange. Die *_saved_queue-Tools arbeiten mit der serverseitigen Warteschlange von Navidrome (Web-UI-Synchronisierung). Die *_play_queue-Tools arbeiten mit der lokalen mpv-Wiedergabeliste.

Entwicklung

git clone https://github.com/Blakeem/Navidrome-MCP.git
cd Navidrome-MCP
pnpm install
pnpm build
node dist/config-app/main.js   # opens the settings page; fill in + Save
# (writes settings.json to your OS config dir; see settings.example.json)

pnpm dev          # hot reload
pnpm test         # watch-mode tests
pnpm test:run     # one-shot tests
pnpm check:all    # lint + typecheck + dead-code
pnpm build        # production bundle

Testen des eigenständigen Web-Players aus einem Dev-Build

Dies ist der Weg aus dem Quellcode, um den Player zu testen, bevor eine Version npm erreicht (das veröffentlichte Paket kann hinter dev zurückliegen). Es gilt auch für den MCP-Server, da beide aus demselben dist/ laufen.

# 1. Build (also bundles the web UI's static assets into dist/)
pnpm build

# 2. Configure if needed; writes settings.json to your OS config dir
node dist/config-app/main.js     # opens the settings page; fill in + Save

# 3. Run the standalone player directly
node dist/web/main.js            # serves http://127.0.0.1:8808 and opens your browser

Um aus diesem Build ein doppelklickbares Symbol zu erstellen (keine globale Installation erforderlich):

pnpm make:launcher               # writes a shortcut to your Desktop + app menu

Windows-Hinweise (PowerShell):

• Verwenden Sie pnpm build und dann node dist\web\main.js, wie oben, aber mit Backslashes.

• pnpm make:launcher schreibt Navidrome Player.vbs auf Ihren Desktop und ins Startmenü. Es startet node dist\web\main.js ohne Konsolenfenster und speichert den absoluten Pfad zu diesem Checkout, also führen Sie es nach dem Verschieben des Ordners erneut aus.

• Wenn ein umgeleiteter/OneDrive-Desktop die Datei versteckt, funktioniert die Kopie im Startmenü weiterhin (Start → „Navidrome“ eingeben).

• mpv muss für die Wiedergabe installiert sein. Setzen Sie playback.mpvPath auf der Einstellungsseite, wenn es nicht auf PATH ist.

Nach npm install -g navidrome-mcp laufen dieselben Abläufe als navidrome-web, navidrome-config und navidrome-web-shortcut ohne Klonen oder Build.

Testen mit MCP Inspector:

pnpm build
npx @modelcontextprotocol/inspector node dist/index.js                  # web UI
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name search_all --tool-arg query="jazz"    # CLI

Lizenz

• Code: AGPL-3.0

• Dokumentation: CC-BY-SA-4.0

Unterstützung

• GitHub Issues

• GitHub Discussions

Mit ❤️ für die Navidrome-Community erstellt