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

Workaround for [anthropics/claude-ai-mcp#664](https://github.com/anthropics/claude-ai-mcp/issues/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`:

```json
"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:

```json
"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 —

```js
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](https://github.com/mujo8), with Claude (Sonnet 4.5).