Filesystem MCP Server

Node.js-Server, der das Model Context Protocol (MCP) für Dateisystemoperationen implementiert.

Veröffentlicht auf npm als @modelcontextprotocol/server-filesystem.

Funktionen

• Dateien lesen/schreiben

• Verzeichnisse erstellen/auflisten/löschen

• Dateien/Verzeichnisse verschieben

• Dateien durchsuchen

• Dateimetadaten abrufen

• Dynamische Verzeichniszugriffskontrolle über Roots

Verzeichniszugriffskontrolle

Der Server verwendet ein flexibles System zur Verzeichniszugriffskontrolle. Verzeichnisse können über Befehlszeilenargumente oder dynamisch über Roots angegeben werden.

Methode 1: Befehlszeilenargumente

Geben Sie beim Starten des Servers erlaubte Verzeichnisse an:

mcp-server-filesystem /path/to/dir1 /path/to/dir2

Methode 2: MCP Roots (empfohlen)

MCP-Clients, die Roots unterstützen, können die erlaubten Verzeichnisse dynamisch aktualisieren.

Roots, die vom Client an den Server gesendet werden, ersetzen vollständig alle serverseitig erlaubten Verzeichnisse, sofern vorhanden.

Wichtig: Wenn der Server ohne Befehlszeilenargumente startet UND der Client das Roots-Protokoll nicht unterstützt (oder leere Roots bereitstellt), löst der Server während der Initialisierung einen Fehler aus.

Dies ist die empfohlene Methode, da sie dynamische Verzeichnisaktualisierungen über roots/list_changed-Benachrichtigungen ohne Serverneustart ermöglicht und so eine flexiblere und modernere Integration bietet.

Funktionsweise

Die Verzeichniszugriffskontrolle des Servers folgt diesem Ablauf:

1. Serverstart

   • Der Server startet mit Verzeichnissen aus Befehlszeilenargumenten (falls angegeben)

   • Wenn keine Argumente angegeben werden, startet der Server mit leeren erlaubten Verzeichnissen

2. Clientverbindung und Initialisierung

   • Der Client verbindet sich und sendet eine initialize-Anfrage mit Fähigkeiten

   • Der Server prüft, ob der Client das Roots-Protokoll unterstützt (capabilities.roots)

3. Roots-Protokollbehandlung (falls der Client Roots unterstützt)

   • Bei Initialisierung: Der Server fordert Roots vom Client über roots/list an

   • Der Client antwortet mit seinen konfigurierten Roots

   • Der Server ersetzt ALLE erlaubten Verzeichnisse durch die Roots des Clients

   • Bei Laufzeitaktualisierungen: Der Client kann notifications/roots/list_changed senden

   • Der Server fordert aktualisierte Roots an und ersetzt erneut die erlaubten Verzeichnisse

4. Fallback-Verhalten (falls der Client Roots nicht unterstützt)

   • Der Server verwendet weiterhin nur die Befehlszeilenverzeichnisse

   • Keine dynamischen Aktualisierungen möglich

5. Zugriffskontrolle

   • Alle Dateisystemoperationen sind auf erlaubte Verzeichnisse beschränkt

   • Verwenden Sie das Werkzeug list_allowed_directories, um die aktuellen Verzeichnisse anzuzeigen

   • Der Server benötigt mindestens EIN erlaubtes Verzeichnis, um zu funktionieren

Hinweis: Der Server erlaubt nur Operationen innerhalb von Verzeichnissen, die entweder über args oder über Roots angegeben wurden.

API

Werkzeuge

• read_text_file

  • Liest den vollständigen Inhalt einer Datei als Text

  • Eingaben:

    • path (string)

    • head (number, optional): Erste N Zeilen

    • tail (number, optional): Letzte N Zeilen

  • Behandelt die Datei unabhängig von der Erweiterung immer als UTF-8-Text

  • Es können nicht gleichzeitig head und tail angegeben werden

• read_media_file

  • Liest eine Datei und gibt sie als base64-codierten Inhaltsblock mit ihrem MIME-Typ zurück

  • Eingaben:

    • path (string)

  • Streamt die Datei und gibt base64-Daten mit dem entsprechenden MIME-Typ zurück. Bild- und Audiodateien werden als image/audio-Inhalt zurückgegeben; jeder andere Dateityp wird als eingebettete resource zurückgegeben (ein gültiger MCP-Inhaltsblock für beliebige Binärdaten)

• read_multiple_files

  • Liest mehrere Dateien gleichzeitig

  • Eingabe: paths (string[])

  • Fehlgeschlagene Lesevorgänge stoppen nicht die gesamte Operation

• write_file

  • Erstellt eine neue Datei oder überschreibt eine vorhandene (Vorsicht walten lassen)

  • Eingaben:

    • path (string): Dateipfad

    • content (string): Dateiinhalt

• edit_file

  • Führt gezielte Änderungen mit erweitertem Musterabgleich und Formatierung durch

  • Funktionen:

    • Zeilen- und mehrzeiliger Inhaltsabgleich

    • Leerraumnormalisierung mit Einrückungserhaltung

    • Mehrere gleichzeitige Änderungen mit korrekter Positionierung

    • Erkennung und Erhaltung des Einrückungsstils

    • Git-ähnliche Diff-Ausgabe mit Kontext

    • Vorschau von Änderungen mit Trockenlaufmodus

  • Eingaben:

    • path (string): Zu bearbeitende Datei

    • edits (array): Liste der Bearbeitungsvorgänge

      • oldText (string): Zu suchender Text (kann Teilzeichenfolge sein)

      • newText (string): Text, durch den ersetzt werden soll

    • dryRun (boolean): Änderungen in der Vorschau anzeigen, ohne sie anzuwenden (Standard: false)

  • Gibt detaillierte Diff- und Trefferinformationen für Trockenläufe zurück, andernfalls werden Änderungen angewendet

  • Best Practice: Verwenden Sie immer zuerst dryRun, um Änderungen vor der Anwendung in der Vorschau anzuzeigen

• create_directory

  • Erstellt ein neues Verzeichnis oder stellt sicher, dass es existiert

  • Eingabe: path (string)

  • Erstellt bei Bedarf übergeordnete Verzeichnisse

  • Wird stillschweigend erfolgreich ausgeführt, wenn das Verzeichnis existiert

• list_directory

  • Listet Verzeichnisinhalte mit Präfixen [FILE] oder [DIR] auf

  • Eingabe: path (string)

• list_directory_with_sizes

  • Listet Verzeichnisinhalte mit Präfixen [FILE] oder [DIR] auf, einschließlich Dateigrößen

  • Eingaben:

    • path (string): Aufzulistender Verzeichnispfad

    • sortBy (string, optional): Einträge nach "name" oder "size" sortieren (Standard: "name")

  • Gibt detaillierte Auflistung mit Dateigrößen und zusammenfassenden Statistiken zurück

  • Zeigt Gesamtzahl der Dateien, Verzeichnisse und kombinierte Größe

• move_file

  • Verschiebt oder benennt Dateien und Verzeichnisse um

  • Eingaben:

    • source (string)

    • destination (string)

  • Schlägt fehl, wenn das Ziel existiert

• search_files

  • Durchsucht rekursiv nach Dateien/Verzeichnissen, die Mustern entsprechen oder nicht entsprechen

  • Eingaben:

    • path (string): Startverzeichnis

    • pattern (string): Suchmuster

    • excludePatterns (string[]): Muster ausschließen

  • Glob-ähnlicher Musterabgleich

  • Gibt vollständige Pfade zu den Treffern zurück

• directory_tree

  • Gibt rekursive JSON-Baumstruktur des Verzeichnisinhalts zurück

  • Eingaben:

    • path (string): Startverzeichnis

    • excludePatterns (string[]): Muster ausschließen. Glob-Formate werden unterstützt.

  • Rückgabe:

    • JSON-Array, in dem jeder Eintrag enthält:

      • name (string): Datei-/Verzeichnisname

      • type ('file'|'directory'): Eintragstyp

      • children (array): Nur bei Verzeichnissen vorhanden

        • Leeres Array für leere Verzeichnisse

        • Bei Dateien weggelassen

  • Ausgabe ist zur besseren Lesbarkeit mit 2 Leerzeichen eingerückt

• get_file_info

  • Ruft detaillierte Datei-/Verzeichnismetadaten ab

  • Eingabe: path (string)

  • Rückgabe:

    • Größe

    • Erstellungszeit

    • Änderungszeit

    • Zugriffszeit

    • Typ (Datei/Verzeichnis)

    • Berechtigungen

• list_allowed_directories

  • Listet alle Verzeichnisse auf, auf die der Server zugreifen darf

  • Keine Eingabe erforderlich

  • Rückgabe:

    • Verzeichnisse, aus denen dieser Server lesen/schreiben kann

Werkzeugannotationen (MCP-Hinweise)

Dieser Server setzt MCP ToolAnnotations auf jedem Werkzeug, damit Clients:

• schreibgeschützte Werkzeuge von schreibfähigen Werkzeugen unterscheiden können.

• verstehen, welche Schreibvorgänge idempotent sind (sicher mit denselben Argumenten wiederholbar).

• Vorgänge hervorheben können, die zerstörerisch sein können (Daten überschreiben oder stark verändern).

• signalisieren, dass ein Werkzeug keine offene oder externe Welt erreicht (jedes Dateisystemwerkzeug setzt openWorldHint: false).

Die Zuordnung für Dateisystemwerkzeuge ist:

Hinweis: idempotentHint und destructiveHint sind nur sinnvoll, wenn readOnlyHint false ist, wie in der MCP-Spezifikation definiert. Jedes Werkzeug setzt auch openWorldHint: false – dieser Server greift nur auf das lokale Dateisystem innerhalb seiner erlaubten Verzeichnisse zu, niemals auf eine offene oder externe Welt.

Verwendung mit Claude Desktop

Fügen Sie dies zu Ihrer claude_desktop_config.json hinzu:

Hinweis: Sie können dem Server sandboxierte Verzeichnisse bereitstellen, indem Sie sie in /projects einbinden. Das Hinzufügen des Flags ro macht das Verzeichnis für den Server schreibgeschützt.

Docker

Hinweis: Standardmäßig müssen alle Verzeichnisse in /projects eingebunden werden.

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

Unter Windows verwenden Sie cmd /c, um npx zu starten:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

Verwendung mit VS Code

Für eine schnelle Installation klicken Sie auf die Installationsschaltflächen unten...

Für die manuelle Installation können Sie den MCP-Server mit einer dieser Methoden konfigurieren:

Methode 1: Benutzerkonfiguration (Empfohlen) Fügen Sie die Konfiguration zu Ihrer benutzerspezifischen MCP-Konfigurationsdatei hinzu. Öffnen Sie die Befehlspalette (Strg + Umschalt + P) und führen Sie MCP: Open User Configuration aus. Dadurch wird Ihre Benutzerdatei mcp.json geöffnet, in der Sie die Serverkonfiguration hinzufügen können.

Methode 2: Arbeitsbereichskonfiguration Alternativ können Sie die Konfiguration zu einer Datei namens .vscode/mcp.json in Ihrem Arbeitsbereich hinzufügen. Dadurch können Sie die Konfiguration mit anderen teilen.

Weitere Details zur MCP-Konfiguration in VS Code finden Sie in der offiziellen VS Code MCP-Dokumentation.

Sie können dem Server sandboxed Verzeichnisse bereitstellen, indem Sie sie unter /projects einhängen. Das Hinzufügen des Flags ro macht das Verzeichnis für den Server schreibgeschützt.

Docker

Hinweis: Alle Verzeichnisse müssen standardmäßig unter /projects eingehängt werden.

{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

Unter Windows verwenden Sie:

{
  "servers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

Build

Docker-Build:

docker build -t mcp/filesystem -f src/filesystem/Dockerfile .

Lizenz

Dieser MCP-Server ist unter der MIT-Lizenz lizenziert. Das bedeutet, dass Sie die Software frei nutzen, modifizieren und verbreiten können, vorbehaltlich der Bedingungen der MIT-Lizenz. Weitere Einzelheiten finden Sie in der LICENSE-Datei im Projekt-Repository.