MCP unter Windows: npx, JSON-Pfade und WSL prüfen

Wenn ein MCP-Server im Terminal startet, im Editor aber nicht, prüfen Sie zuerst die Ausführungsumgebung. Windows, WSL und ein Container sind verschiedene Orte für Programme und Dateien. Notieren Sie, wo der Editor den Server startet, welches Programm aufgerufen wird und wo der freigegebene Ordner liegt. Diese drei Angaben sind nützlicher als mehrere gleichzeitig geänderte Konfigurationsdateien. Der folgende Ablauf beginnt mit einem neu angelegten Testordner ohne bestehende Dokumente.

Windows und WSL als getrennte Umgebungen behandeln

Ein Windows-Programm erwartet nicht automatisch einen Linux-Pfad. Umgekehrt ist ein Windows-Laufwerksbuchstabe kein gewöhnlicher absoluter Linux-Pfad. Microsoft beschreibt den Zugriff auf Windows-Laufwerke aus WSL über /mnt/. Prüfen Sie den tatsächlichen Startkontext, bevor Sie einen solchen Pfad einsetzen. Für Container ergänzt der Docker-Leitfaden die Zuordnung von Hostordner und eingebundenem Ziel.

Ein Filesystem-Beispiel für Windows lesen

Das Beispiel verwendet einen mcpServers-Block und den vom Filesystem-Projekt dokumentierten Windows-Start über cmd /c. Erstellen Sie C:\mcp-test vor dem Versuch und legen Sie dort nur erfundene Testdaten ab. Passen Sie das Dateiformat an Ihren Client an. Vom Client bereitgestellte MCP Roots können die Ordnerliste ersetzen. Kontrollieren Sie deshalb vor dem ersten Zugriff list_allowed_directories. Die eingeräumte Ordnergrenze macht den Server nicht automatisch schreibgeschützt; wählen Sie für die erste Probe ausdrücklich eine lesende Operation.

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\mcp-test"
      ]
    }
  }
}

In der JSON-Datei stehen Backslashes doppelt. Nach dem Einlesen bezeichnet C:\\mcp-test den Pfad mit einem einzelnen Trennzeichen. Ein Ordnername mit Leerzeichen bleibt ein einzelnes Element in args; zusätzliche Anführungszeichen innerhalb dieses Werts sind nicht pauschal nötig. Vermischen Sie ein JSON-Argumentfeld nicht mit einer fertig zusammengesetzten Terminalzeile. Bei Unsicherheit prüfen Sie zuerst die Syntax in der Konfigurationsprüfung.

Programm, Argumente und Zugriff getrennt prüfen

1. Prüfen Sie in der passenden Umgebung, ob Node und npx gefunden werden. Notieren Sie Programmpfad und Version ohne Ihre vollständige Umgebung zu veröffentlichen.

2. Überprüfen Sie den JSON-Block und die Reihenfolge der Argumente. Ergänzen Sie den einen Server in der vorhandenen Clientdatei.

3. Starten Sie den Server im Client und sehen Sie sich dessen konkrete Fehlermeldung an. ENOENT vor dem Start und ein später verweigerter Ordnerzugriff sind unterschiedliche Probleme.

4. Lassen Sie eine eigens angelegte Testdatei lesen. Vergleichen Sie ihren Inhalt, stoppen Sie den Server und halten Sie fest, welcher Pfad tatsächlich verwendet wurde.

Den nächsten Schritt am Fehlerbild auswählen

Bei einem fehlenden Startprogramm hilft die ENOENT-Anleitung. Läuft der Prozess, aber fehlen Werkzeuge oder Dateien, führen Sie keine Neuinstallation auf Verdacht durch. Vergleichen Sie Ordner, Benutzer und Serverargumente mit dem erfolgreichen Terminalversuch. Der Filesystem-Leitfaden vertieft die Zugriffsgrenze. Ein erfolgreicher Lesetest auf einem Rechner bestätigt noch keine Einrichtung unter WSL oder auf dem Rechner eines Kollegen.

Muss jedes Programm mit cmd starten?

Nein. Das Beispiel betrifft den dokumentierten npx-Start unter Windows. Übertragen Sie den Wrapper nicht ungeprüft auf andere Programme.

Ist ein Linux-Pfad unter Windows richtig?

Nur wenn der Prozess in der dazugehörigen Umgebung läuft. Prüfen Sie, wer den Server startet und wo der Ordner existiert.

Ist ein gültiges JSON bereits eine erfolgreiche Einrichtung?

Nein. Syntax, Programmstart und Dateioperation sind drei getrennte Prüfungen mit jeweils eigenem Ergebnis.

Darf ich sofort meinen Dokumentenordner freigeben?

Für den ersten Test ist ein eigener Ordner mit erfundenen Daten leichter abzugrenzen und anschließend aufzuräumen.

Herstellerquellen, abgerufen am 1. Oktober 2026. Die Prüfabläufe sind redaktionelle Vorschläge.

1. MCP Filesystem: Windows configuration
   Abrufbefehl anzeigen

   curl -s https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem
2. Microsoft: WSL filesystems
   Abrufbefehl anzeigen

   curl -s https://learn.microsoft.com/en-us/windows/wsl/filesystems
3. Node.js: child processes on Windows
   Abrufbefehl anzeigen

   curl -s https://nodejs.org/api/child_process.html#spawning-bat-and-cmd-files-on-windows

Alle Beiträge