fsshim — drop-in replacement for the blocked Filesystem MCP server

Workaround for anthropics/claude-ai-mcp#664: after a Claude Desktop update, every tool call to the bundled Filesystem MCP server fails with Tool execution failed. The server is healthy and completes initialize + tools/list, but tools/call never reaches it.

---

⚠️ Try this first — you probably don't need this repo

Reported working on Windows 11 and macOS, and it is far simpler than anything here:

Settings → Extensions → Advanced settings → turn OFF "Use Built-in Node.js for MCP"

With Desktop's bundled Node disabled, it falls back to your system Node and the stock bundled filesystem server works again — unmodified, no config surgery, no third-party code to maintain.

Requires Node installed on your system (any recent version; v20/v22/v24 all reported fine). If you have that, do this instead of using this repo and stop reading.

This repo is for the case where you don't have system Node, can't install it, or want the symlink-hardening notes below.

---

Install

mkdir C:\mcp\fsshim        # or wherever
cd C:\mcp\fsshim
# drop server.js + package.json here
npm install

Node 18+ (tested on 22 and 24).

Config

In claude_desktop_config.json, replace what the existing filesystem entry runs — keep the connector name filesystem:

"filesystem": {
  "command": "node",
  "args": [
    "C:\\mcp\\fsshim\\server.js",
    "C:\\your\\first\\allowed\\root",
    "C:\\your\\second\\allowed\\root"
  ]
}

Every path after server.js is an allowed root. Same semantics as the bundled server.

Then fully quit Claude Desktop (Task Manager / force quit — not just closing the window) and relaunch.

Smoke-test before trusting it

node C:\mcp\fsshim\server.js "C:\your\allowed\root"

It should print nothing and hang, waiting on stdin. That silence is the pass condition — an MCP stdio server blocks until a client speaks to it. Anything printed to stdout corrupts the JSON-RPC stream. Ctrl-C to exit.

WSL note

If your node lives inside WSL under a version manager (fnm/nvm), wsl -e node will not find it — -e doesn't source your shell profile. Either run the shim with Windows-side node (simplest, use \\wsl.localhost\... paths for WSL roots), or launch it through a login shell:

"command": "wsl",
"args": ["bash", "-lc", "exec node /home/you/fsshim/server.js /mnt/c/your/root"]

Tools

Deliberately the same names as the bundled server, so nothing downstream has to change:

list_allowed_directories · list_directory · read_file · read_multiple_files · write_file · create_directory · move_file · get_file_info · directory_tree · search_files

Some workarounds circulating for #664 rename the tools (fs_ls, fs_read, …) on the theory that the tool names are what gets blocked. Tested A/B against the live broken client — same server code, two builds, only the names differing — both work. list_directory dispatches fine as soon as something other than the bundled server is serving it, so renaming buys nothing and costs you every prompt and script that already knows the original names.

Given the built-in-Node finding above, the likeliest reading is that the bundled Node runtime is the broken part and any externally-spawned process sidesteps it — which also explains why renaming appeared to work. Either way: don't rename.

Two things worth knowing if you build your own

1. Pin zod. The MCP SDK pulls it in transitively today. If that ever changes, require('zod') dies with no obvious cause. It's declared explicitly in package.json here.

2. A prefix check is not containment. The obvious guard —

path.resolve(p).startsWith(root)   // NOT enough

— doesn't follow symlinks. A symlink planted inside an allowed root pointing outside it passes this check and the OS then happily follows it. Reproduced live before fixing:

list_directory(<root>/escape_link)   ->  [FILE] secret.txt      # outside the root. leak.

The fix is to resolve the real physical path first (fs.realpath, walking up to the nearest existing ancestor for paths that don't exist yet), then containment-check. After the fix, the same attack:

list_directory(<root>/escape_link)          -> Error: Path outside allowed roots
read_file(<root>/escape_link/secret.txt)    -> Error: Path outside allowed roots
write_file(<root>/escape_link/pwned.txt)    -> Error: Path outside allowed roots   (nothing written)

directory_tree and search_files also refuse to descend symlinks, so an in-root symlink can't leak outside filenames either. Blocked attempts are appended to fsshim-audit.log next to the server.

This one is worth flagging regardless of #664: it applies to any MCP server that hands out filesystem access from a fixed set of roots.

Status

Not affiliated with Anthropic. A workaround for a client-side regression, not a fix — the underlying bug is theirs. Delete this and go back to the bundled server once it's patched.

Credit for the built-in-Node toggle goes to whoever surfaced it on Reddit / in the issue thread; it's the better first move and is documented above accordingly.

---

Implementation and the symlink/containment notes: @mujo8, with Claude (Sonnet 4.5).