mcp-filesystem

A hardened filesystem MCP server. Gives a local model read and write access to a set of directories you choose — and nothing else.

Built on the MCP TypeScript SDK v2 against the 2026-07-28 protocol revision, with backward compatibility for 2025-era clients on the same endpoint. Runs over stdio (for LM Studio, Claude Desktop, and anything else that spawns a local process) or Streamable HTTP (for a containerised shared endpoint).

Why this one

Most filesystem MCP servers check that a path starts with an allowed prefix and call it a day. That misses three things that matter:

• Symlinks. A link planted inside the sandbox pointing at /etc defeats a prefix check entirely.

• Writes through symlinked directories. realpath throws on paths that don't exist yet, so servers that only resolve existing files will happily create sandbox/linkdir/payload.sh outside the sandbox.

• Prefix collisions. /data-secrets starts with /data.

This server resolves every path to its physical location before deciding — walking up to the deepest existing ancestor when the target doesn't exist yet — and compares against realpath'd roots with separator-aware matching. The test suite asserts each of those escapes fails.

Related MCP server: MCP Filesystem Server

Tools

Writes are atomic: content goes to a temp file in the same directory, is fsync'd, then renamed over the target. A crash or full disk leaves the original intact rather than truncated.

Quick start

npm install
npm run build
npm test

Then point a client at it:

node dist/index.js --root ./workspace

Or try it interactively without configuring a client:

npx @modelcontextprotocol/inspector node dist/index.js --root ./workspace

LM Studio

LM Studio reads ~/.lmstudio/mcp.json (on Windows, C:\Users\<you>\.lmstudio\mcp.json). Open it from Program → Install → Edit mcp.json, add an entry under mcpServers, then reload LM Studio.

Running it natively

The lowest-friction option, and the one to start with.

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-file-system/dist/index.js",
        "--root", "/absolute/path/to/your/project",
        "--read-only"
      ]
    }
  }
}

Drop --read-only once you trust it. Add more --root flags for more directories.

These two paths must be absolute. The host spawns the server as a child process with an unpredictable working directory, so a relative path will not resolve. On the command line, where you control the working directory, relative paths like --root ./workspace are fine.

On Windows either write forward slashes (C:/Users/you/projects) or double the backslashes, since a single \ is an escape character inside a JSON string.

Running it in Docker

Docker gives you a kernel-enforced boundary underneath the server's own checks, which is the real argument for it: even a bug in the sandbox code can't reach anything you didn't mount.

docker build -t mcp-filesystem:latest .

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "--network", "none",
        "-v", "/absolute/path/to/your/project:/data:ro",
        "mcp-filesystem:latest",
        "--stdio", "--read-only"
      ]
    }
  }
}

Notes:

• -i is required. Without it the container gets no stdin and the JSON-RPC handshake never happens — this is the single most common misconfiguration.

• --network none is worth setting: this server has no reason to reach the network, and removing the interface removes a whole class of exfiltration.

• :ro on the mount makes read-only enforcement the kernel's job. To allow writes, drop :ro and drop --read-only.

• Docker requires the host side of -v to be an absolute path.

• On Docker Desktop for Windows, the drive you are mounting from must be shared under Settings → Resources → File sharing.

• On a Linux host, add --user "$(id -u):$(id -g)" so written files are owned by you rather than uid 1000.

Mount several directories by repeating -v and passing matching --root flags:

"-v", "/absolute/path/to/your/code:/data/code:ro",
"-v", "/absolute/path/to/your/notes:/data/notes",
"mcp-filesystem:latest",
"--stdio", "--root", "/data/code", "--root", "/data/notes"

HTTP transport

For a long-lived container that several clients share:

docker compose up -d
curl http://127.0.0.1:3000/health

Point a client at http://127.0.0.1:3000/.

This server has no authentication. Anyone who can reach the port has whatever filesystem access the server has. docker-compose.yml publishes to 127.0.0.1 only. If you bind it anywhere else, put an authenticating reverse proxy in front, and expect the startup log to warn you.

When bound to loopback the server validates Host and Origin headers to block DNS-rebinding — a web page you visit resolving an attacker-controlled domain to 127.0.0.1 and POSTing to this port.

Configuration

Every flag has an environment-variable equivalent, which is what the container uses. CLI flags win.

The server refuses to start with no roots configured. A filesystem server with no sandbox is not a safe default, and defaulting to the working directory just makes the mistake quiet.

Default deny list

Blocked unless you pass --allow-default-denied: .env and .env.*, *.pem, *.key, *.p12, *.pfx, *.keystore, id_rsa/id_dsa/id_ecdsa/ id_ed25519, .ssh/, .aws/, .gnupg/, .kube/config, .npmrc, .netrc, .pypirc, .docker/config.json, .git/, .svn/, .hg/, shadow.

This exists so that a careless -v $HOME:/data is survivable. It is a safety net, not a substitute for mounting the right directory.

Security model

What's enforced

• Physical path resolution (realpath) before every containment decision, including for paths that don't exist yet

• Separator-aware root matching (/data never matches /data-secrets)

• Symlinks rejected by default, in any path position — not just the leaf

• NUL-byte rejection (safe.txt\0/../../etc/passwd truncates in the syscall)

• Windows: alternate data streams (file:stream), reserved device names (CON, NUL, COM1…), device-namespace paths (\\?\, \\.\), and case-insensitive containment

• Read-only mode gates mutating tools before the handler runs

• Both operands checked on move/copy — a source-only check is a write primitive for the whole host

• Allowed roots cannot themselves be deleted or moved

• Size caps checked via stat before allocating

• Binary detection, so binaries aren't returned as token-burning garbage

• Regex screening and a wall-clock deadline on grep_files

• Error messages never echo host paths; SecurityError returns a vague message to the model and logs the real reason to the audit stream, so the sandbox isn't an oracle for mapping your filesystem

What isn't

• TOCTOU. Between resolving a path and opening it, a local attacker who can write inside your allowed roots could swap a file for a symlink. Closing this needs openat2(RESOLVE_BENEATH) on Linux, which Node doesn't expose. The practical mitigation is the container boundary — mount only what you mean to expose.

• Authentication. Neither transport authenticates. stdio inherits the trust of whoever spawned the process; HTTP is loopback-only for that reason.

• Resource exhaustion. Caps and deadlines bound most things, but a pathological regex can still burn one 15-second deadline of CPU. The compose file sets memory and CPU limits.

• Prompt injection. If a file inside your sandbox contains instructions and your model follows them, this server will faithfully execute whatever tools the model calls next. Read-only mode is the mitigation that actually works.

Container hardening (in docker-compose.yml): non-root user, read_only root filesystem, all capabilities dropped, no-new-privileges, tmpfs /tmp, memory and CPU limits.

Audit log

One JSON object per line on stderr — never stdout, which is the JSON-RPC channel under stdio. console.log is monkey-patched to redirect to stderr at startup so a stray debug statement can't corrupt the protocol stream.

{"ts":"2026-08-21T19:12:03.441Z","tool":"read_file","outcome":"ok","durationMs":3,"paths":["src/index.ts"],"bytes":4821}
{"ts":"2026-08-21T19:12:07.882Z","tool":"read_file","outcome":"denied","durationMs":1,"detail":"physical containment failed: /data/../etc/passwd -> /etc/passwd"}

Logged paths are sandbox-relative. The detail field carries the full reason and is only ever written here, never returned to the model.

docker compose logs -f filesystem | jq 'select(.outcome=="denied")'

Tests

npm run build && npm test

test/sandbox.test.ts is the suite that matters — every case is an attempt to reach a file outside the root. If one of them starts passing where it should throw, the server is broken in the only way that's genuinely dangerous.

Symlink tests skip themselves on Windows unless Developer Mode is on, since creating symlinks otherwise needs admin rights.

Project layout

src/
  index.ts              entrypoint, transport selection, shutdown
  config.ts             CLI + env parsing, root resolution
  security/
    sandbox.ts          path resolution and containment — the security core
    audit.ts            structured stderr logging, stdout protection
  tools/
    context.ts          registration wrapper: read-only gate, errors, audit
    read.ts             read_file, read_multiple_files, get_file_info, ...
    write.ts            write_file, append_file, edit_file
    listing.ts          list_directory, directory_tree
    manage.ts           create_directory, move_file, copy_file, delete_file
    search.ts           search_files, grep_files
  util/
    walk.ts             sandbox-aware directory traversal with cycle guard
    binary.ts           binary detection, BOM handling
    errors.ts           error taxonomy and fs error translation
    format.ts           output formatting for model consumption

License

MIT