MCP Server Official reference

Filesystem

Node.js MCP server for filesystem operations (read, write, edit, search, list) restricted to allowed directories set via CLI args or MCP Roots.

  • 91.1k GitHub stars
View on GitHub (opens in a new tab) Setup guide
docker build -t mcp/filesystem -f src/filesystem/Dockerfile .
Filesystem preview image

What it is

Filesystem MCP Server is a Node.js server implementing the Model Context Protocol for filesystem operations. It is published on npm as @modelcontextprotocol/server-filesystem. It can read and write files, create/list/delete directories, move files, search files, and return file metadata. All operations are restricted to allowed directories, which come from command-line arguments or dynamically from MCP Roots.

Who it's for

  • Developers who want an MCP client such as Claude Desktop or VS Code to access local files within restricted directories
  • Teams that want sandboxed, optionally read-only, directory access through Docker mounts
  • Users of MCP clients that support Roots who want to change allowed directories at runtime without restarting the server

Requirements

Requirements

  • At least one allowed directory, provided via command-line arguments or via client Roots, otherwise the server throws an error during initialization
  • Node.js with npx (for the NPX method) or Docker (for the Docker method)
  • An MCP client such as Claude Desktop or VS Code

Setup

  1. Claude Desktop with NPX

    Add this to your claude_desktop_config.json, replacing the directory paths with the directories you want to allow.

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

  2. Claude Desktop with Docker

    Mount directories under /projects. Adding the ro flag makes a mount read-only for the server.

    json
    {
  "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"
      ]
    }
  }
}

  3. VS Code with NPX

    Add to your user mcp.json (via the MCP: Open User Configuration command) or to .vscode/mcp.json in your workspace.

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

  4. Windows launch

    On Windows, use cmd /c to launch npx.

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

  5. Build the Docker image

    Build the image locally from the repository.

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

Examples

Start the server with allowed directories

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

What it does: Specifies allowed directories as command-line arguments (Method 1 of directory access control).

Preview an edit with dryRun

json
json
{
  "path": "<file to edit>",
  "edits": [
    { "oldText": "<text to search for>", "newText": "<text to replace with>" }
  ],
  "dryRun": true
}

What it does: Inputs for the edit_file tool using the documented fields. The README recommends dryRun first, which returns a detailed diff and match information without applying changes.

Check which directories are accessible

Prompt
prompt
Use list_allowed_directories to show which directories you can access.

Expected output: The list_allowed_directories tool takes no input and returns the directories the server can read and write.

List a directory with sizes

Prompt
prompt
Use list_directory_with_sizes on <path>, sorted by size.

Expected output: The tool accepts path and an optional sortBy of "name" or "size", and returns file sizes plus total files, directories and combined size.

Pros & cons

Pros

  • Pro:Access is restricted to allowed directories set by CLI arguments or MCP Roots
  • Pro:Roots support allows runtime directory updates via roots/list_changed notifications without a server restart
  • Pro:Docker mounts can be made read-only with the ro flag
  • Pro:Tools carry MCP annotations (readOnly, idempotent, destructive hints), and edit_file offers dry-run diff previews

Cons

  • Con:Fails at initialization if no command-line directories are given and the client lacks Roots support or provides empty roots
  • Con:write_file overwrites existing files and move_file fails if the destination exists, so care is needed
  • Con:Roots from a client completely replace any server-side allowed directories

Images

Filesystem preview image
Filesystem preview image · modelcontextprotocol/servers on GitHub
Filesystem preview image