@j0hanz/filesystem-mcp

v2.7.1

Published

2 days ago

Secure filesystem MCP server for reading, writing, searching, diffing, and patching files.

Filesystem MCP Server

Overview

Filesystem-MCP is a Model Context Protocol server that lets AI assistants read and write files within explicitly allowed directories. Sensitive file patterns (.env, *.pem, *id_rsa*) are blocked by default. It exposes filesystem tools, resources, and prompts over stdio or Streamable HTTP transport.

Features

| Feature | Description | | :--------------------- | :--------------------------------------------------------------------------------------------------------- | | Path guarding | Every path is validated against allowed roots; .env, *.pem, *id_rsa* and similar patterns are denied | | Filesystem tools | Navigate, inspect, read, and write across all major file operations | | Batch operations | Most tools accept path, paths[], or files[] for parallel execution | | Dual transport | stdio by default; --port enables Streamable HTTP for both 2025-era and 2026-07-28 clients | | File subscriptions | Resource subscriptions push change notifications when watched files update | | Regex safety | RE2 in all search tools: linear-time matching, so no pattern can ReDoS the server |

Compared with the reference server

How this server differs from @modelcontextprotocol/server-filesystem, checked against its README and source on 2026-09-24:

Built with

Quick start

[!NOTE] Requires Node.js ≥ 24.

Prerequisites

Install via npx

npx -y @j0hanz/filesystem-mcp /path/to/allowed/dir

Or install globally:

npm install -g @j0hanz/filesystem-mcp
filesystem-mcp /path/to/allowed/dir

Install via Docker

docker run -i --rm \
  -v /path/to/project:/workspace:ro \
  ghcr.io/j0hanz/filesystem-mcp:latest \
  --read-only /workspace

Configure in VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Or install via CLI:

code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","/path/to/project"]}'

Configure in Visual Studio

Add to .vs\mcp.json in your solution directory, or %USERPROFILE%\.mcp.json for a global configuration:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Configure in Claude Desktop

One click: download filesystem-mcp.mcpb, open it with Claude Desktop, and pick the directories to allow. Claude Desktop's built-in Node.js runs it.

Or configure it by hand. Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Install in Cursor

Add to .cursor/mcp.json in your project root (project-scoped), or ~/.cursor/mcp.json for a global configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Install as a plugin

The filesystem-mcp plugin wires the server up with project-scoped defaults:

| Client | Install | | :-------------- | :------------------------------------------------------------------------------------------------------------------------------ | | Claude Code | /plugin marketplace add j0hanz/j0hanz-marketplace, then /plugin install filesystem-mcp@j0hanz-marketplace | | Copilot CLI | copilot plugin marketplace add j0hanz/j0hanz-marketplace, then copilot plugin install filesystem-mcp@j0hanz-marketplace | | Antigravity CLI | git clone https://github.com/j0hanz/j0hanz-marketplace, then agy plugin install ./j0hanz-marketplace/plugins/filesystem-mcp |

The plugin README covers the defaults and how each client picks the project directory.

Docker configuration

VS Code (.vscode/mcp.json) and Visual Studio (.vs\mcp.json):

{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/project:/workspace",
        "ghcr.io/j0hanz/filesystem-mcp:latest",
        "/workspace"
      ]
    }
  }
}

Claude Desktop (claude_desktop_config.json) and Cursor (mcp.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/project:/workspace",
        "ghcr.io/j0hanz/filesystem-mcp:latest",
        "/workspace"
      ]
    }
  }
}

[!NOTE] For least privilege, use both controls: :ro makes the container mount read-only at the operating-system boundary, while the server's --read-only flag removes mutating tools (create, edit, move, delete, patch, replace_text) from tools/list.

Usage

Tools

All tools are scoped to the configured roots. Call list_roots first to discover what is allowed.

Navigate

| Tool | Description | | :----------- | :------------------------------------------------------------------------------------- | | list_roots | List allowed workspace roots. Call this first — all other tools scope to these. | | list | List directory contents. Returns entries (dirs-first, alphabetical) and an ASCII tree. | | find_files | Find files by glob pattern (e.g. **/*.ts). Returns matching files with metadata. |

Inspect

Read

Write

| Tool | Description | | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | create | Create one or more files, creating parent directories as needed. An existing file prompts the user to confirm the overwrite; overwrite: true on an entry skips the prompt, append: true adds to the end instead. | | edit | Apply sequential literal string replacements to one or more files (up to 5 files per call, 100 edits per file). | | move | Move, rename, or copy (copy: true) one or more files/directories to explicit destinations. | | delete | Permanently delete one or more files or directories. This action is irreversible. | | replace_text | Bulk search-and-replace across files matching a glob pattern. | | patch | Apply a single-file unified diff and write the result. |

Resources

| URI | Description | | :------------------------------ | :------------------------------------------------------------------------------------ | | internal://instructions | Server navigation guide — tools overview, constraints, and error recovery. | | filesystem-mcp://file/{+path} | Read a workspace file. Subscribe to receive push notifications on change. | | filesystem-mcp://result/{id} | Ephemeral cached tool output. Expires after ~60 seconds, eviction, or server restart. |

Prompts

Project structure

filesystem-mcp/
├── __tests__/          Test suites (node --test) and shared helpers
├── docs/adr/           Architecture decision records
├── mcpb/manifest.json  Claude Desktop extension manifest
├── scripts/            Release-path scripts (MCPB pack, Smithery publish)
├── src/
│   ├── core/           Path guarding, filesystem facade, search, stores, watchers
│   ├── tools/          One file per tool, plus define.ts (registration) and batch.ts
│   ├── transport/      stdio.ts, http.ts, http-policy.ts (auth, Origin, rate limit), shared.ts
│   ├── cli.ts          Argument parsing and --print-config
│   ├── cli-help.ts     --help / --version text
│   ├── index.ts        Process entrypoint, shutdown, transport selection
│   ├── instructions.ts Server instructions sent to every client
│   ├── prompts.ts      Prompt definitions and registration
│   ├── resources.ts    Resource definitions, subscriptions, completion
│   ├── server.ts       Server factory and registrar composition
│   └── transport.ts    Facade re-exporting startServer / startHttpServer
└── Dockerfile          Multi-stage alpine build, non-root user

Runtime composition flows from src/index.ts to src/transport/ (stdio or HTTP), then to src/server.ts, the registrars, and finally src/core/. Each registrar owns the narrow dependency contract it consumes.

Tools use Zod for runtime input validation and named TypeScript types for results; output schemas are neither validated nor published. defineTool derives wire annotations from each tool's required readOnlyHint. Every server supplies a result store, while file-resource links point directly to guarded reads from disk.

Configuration

The server starts with allowed directories from explicit startup configuration:

Positional directories passed to filesystem-mcp.
Environment variable FS_ALLOWED_DIRS (separated by : on POSIX or ; on Windows).
Current working directory when --allow-cwd is enabled.

When --root-boundary / FS_ROOT_BOUNDARY is set, a configured root that does not fall under it is skipped at startup with a warning; only roots under the boundary (and later grants under it) are allowed.

Legacy MCP connections may additionally seed roots through the deprecated roots/list flow. Modern 2026-07-28 connections do not automatically send workspace roots. They can add access after startup by calling a tool with a concrete path and approving the elicitation-backed grant. list_roots reports the roots already configured or accepted; it cannot discover an unknown workspace by itself.

Over HTTP, 2025-era clients are served statelessly: tools, resources and prompts work. Confirmations (recursive delete, overwrite, access grants) need a 2026-07-28 client or stdio and answer with a tool error saying so; file subscriptions are not advertised on that leg, and a resources/subscribe sent anyway is refused with method-not-found.

Recommended global recipes

VS Code / Cursor / Claude Code (primary recipe)

Configure the project directory explicitly:

Add to your global or project-scoped configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Claude Desktop (fallback recipe via environment variable)

Claude Desktop and similar clients don't support the MCP Roots protocol. Use the FS_ALLOWED_DIRS environment variable to configure allowed folders.

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"],
      "env": {
        "FS_ALLOWED_DIRS": "/path/to/project1:/path/to/project2"
      }
    }
  }
}

(On Windows, separate directories with a semicolon ; instead of a colon :).

Advanced / per-project positional arguments

You can also restrict access to specific directories by passing positional arguments directly:

# Start with explicit positional paths
filesystem-mcp /path/to/project1 /path/to/project2

Configuration reference

CLI flags

| Flag | Default | Purpose | | :------------------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [dirs...] | — | One or more allowed root directories (positional). A whole argument ${NAME} is read from the environment and dropped when unset | | --allow-cwd | false | Also allow the current working directory as a root | | --walk-cwd | false | Walk up from CWD to find a project root; implies --allow-cwd | | --allow-missing-roots | false | Start even if configured allowed directories do not exist | | --port <n> | — | Enable Streamable HTTP transport on the given port (env: FS_PORT) | | --http-host <host> | — | HTTP server bind address (env: FS_HTTP_HOST) | | --api-key <key> | — | Require this API key on HTTP requests (env: FS_API_KEY) | | --read-only | false | Disable write tools: create, edit, delete, move, patch, replace_text | | --deny <pattern> | — | Block paths matching this pattern; repeatable | | --allow <pattern> | — | Exempt a pattern from the built-in sensitive denylist; repeatable (env: FS_ALLOWLIST). Does not lift --deny/FS_DENYLIST entries | | --allow-sensitive | false | Allow access to sensitive system paths (env: FS_ALLOW_SENSITIVE) | | --root-boundary <path> | — | Require all allowed roots to fall under this path (env: FS_ROOT_BOUNDARY) | | --max-file-size <bytes> | — | Maximum file size for reads and the combined content of one create call, in bytes (env: FS_MAX_FILE_SIZE). Each transport accepts one message of up to 3 × this + 1 MiB | | --log-level <level> | info | RFC 5424 log level, debug through emergency (env: FS_LOG_LEVEL) | | --print-config | false | Print the active configuration as JSON (roots, tools, limits, policy, supported protocol revisions, SDK pins) and exit |

--deny and --allow patterns support * (any run within a segment), ** (any run of segments), ?, [...] classes, and {a,b} alternation. Dot-leading (hidden) names match like any other — secrets/** denies secrets/.env, *id_rsa* denies .id_rsa.

Environment variables

All boolean variables accept true or 1 to enable and false, 0, or unset to disable; any other value logs a warning and reads as disabled. Flags take precedence when both are set.

| Variable | :---------------------------- | FS_ALLOWED_DIRS | FS_ROOT_BOUNDARY | FS_ALLOW_CWD_WALK | FS_ALLOW_MISSING_ROOTS | FS_ALLOW_SENSITIVE | FS_DENYLIST | FS_ALLOWLIST | FS_MAX_FILE_SIZE | FS_LOG_LEVEL | FS_PORT | FS_HTTP_HOST | FS_API_KEY | FS_TRUST_PROXY | FS_ALLOWED_HOSTS | FS_ALLOWED_ORIGINS | FS_ALLOW_UNRESTRICTED_HOSTS | FS_PUBLIC_URL | FS_RATE_LIMIT_RPM | FS_MAX_WATCHERS | NO_COLOR | FS_REQUEST_STATE_KEY | Purpose | | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Colon-separated (POSIX) or semicolon-separated (Windows) list of directories to allow. | | Path prefix all allowed roots must fall under (mirrors --root-boundary). | | Walk up from CWD to find a project root (mirrors --walk-cwd). | | Start even if configured directories do not exist (mirrors --allow-missing-roots). | | Allow access to sensitive system paths (mirrors --allow-sensitive). | | Comma-separated list of paths or patterns to block (mirrors --deny). | | Comma-separated patterns exempted from the built-in sensitive denylist (mirrors --allow). Never lifts FS_DENYLIST/--deny entries. | | Maximum file size for reads and for one create call's combined content, in bytes (mirrors --max-file-size). Also sizes the per-message wire limit: 3 × this + 1 MiB. | | RFC 5424 log level: debug, info, notice, warn/warning, error, critical, alert, or emergency (mirrors --log-level). | | Start the Streamable HTTP transport on this port; unset = stdio (mirrors --port). | | HTTP server bind address (mirrors --http-host). | | API key required on HTTP requests (mirrors --api-key). | | Express trust proxy setting: hop count or expression. Unset = do not trust X-Forwarded-*. | | Comma-separated Host header values to accept (HTTP transport). | | Comma-separated origin hostnames allowed to call /mcp from a browser. Replaces the localhost default, so also list localhost, 127.0.0.1 or [::1] if local browser clients still need access. | | Bind a wildcard host with no Host validation (accepts the risk). | | Resource identifier URL for RFC 9728 discovery. | | Per-client-IP requests/minute (default 120 with API-key authentication, 6,000 for keyless loopback; range 1–100000). | | Max concurrent file watchers (default 256, 1–4096). | | Any value disables ANSI color output. | | HMAC key sealing input_required requestState across retry rounds. Optional (random per boot if unset); set it, at >=32 bytes UTF-8, to keep in-flight rounds alive across a restart. |

Examples

# Allow current working directory
filesystem-mcp --allow-cwd

# HTTP transport on port 3000
filesystem-mcp --port 3000

Scripts

Security

[!IMPORTANT] Report vulnerabilities privately via GitHub Security Advisories. Do not open public issues for security reports.

Contributing

Fork the repository.
Create a feature branch: git checkout -b feat/your-feature.
Commit your changes with a clear message.
Run npm run check to confirm tests, types, lint, formatting, and knip all pass.
Open a pull request.

Privacy Policy

filesystem-mcp runs entirely on your machine. This policy covers the npm package, the Docker image, and the .mcpb desktop extension.

Data collection: none. The server has no telemetry, analytics, or crash reporting, and makes no outbound network requests.
Use and storage: files are read and written only inside the directories you allow, and only when your MCP client calls a tool. Tool results go to that client and nowhere else. Short-lived result caches live in memory and disappear when the server exits.
Third-party sharing: none by this server. Your MCP client may send tool results to its model provider under that client's own privacy policy.
Retention: nothing is kept after the process exits. Diagnostic logs go to stderr on your machine; your MCP client may save them in its own log files.
Contact: open an issue at https://github.com/j0hanz/filesystem-mcp/issues, or report security problems privately through GitHub Security Advisories.

License

Released under the MIT License. See LICENSE for details.