mcp-fs-shell-windows — filesystem + standalone Windows shell MCP server

A Windows-first MCP server that gives AI clients comprehensive filesystem access (batched read/write/search/patch across your chosen drives and UNC shares) plus reliable local shell execution (synchronous, background, and interactive) — in a single Node.js process with no client-side permission toggles.

Heavily extended fork of fabienvauchelles/mcp-filesystem-extended, which itself extends the official @modelcontextprotocol/server-filesystem. Developed and tested primarily on Windows: drive-letter roots (C:\, D:\) and UNC network-share roots (\\server\\share) are first-class, and the shell tools run commands through cmd.exe byte-for-byte.

npm: mcp-fs-shell-windows · Source: gerarddeluca/mcp-fs-shell-windows

Provenance

Related MCP server: Sky Windows Remote Executor

Features

• 23 filesystem tools — batched read/write/append/delete, move/copy, line-number patching, search (name / glob / regex / fuzzy), tree, counts, checksums, diffs, exact-match text editing. Confined to the allowed directories passed on the command line.

• 8 shell tools — synchronous, background, and interactive command execution implemented inside the MCP server process: no client-side permission toggles, survives client restarts, works with any MCP client.

• Windows-first — drive roots, UNC roots, cmd.exe /d /c with verbatim argv, whole-process-tree kills (taskkill /T /F), detached interactive console windows.

• NAS-safe startup — an allowed directory that is missing or offline (e.g., a powered-down network share) logs a warning and the server continues instead of exiting.

Requirements

• Node.js >= 20 (developed and tested on Node 22).

• Windows for the shell tools (they spawn cmd.exe, taskkill, and powershell). The filesystem tools work on any platform Node runs on.

• shell_python requires Python on the system PATH.

Quick start (npm)

Published on npm — npx downloads the server (and all dependencies) and runs it:

npx -y mcp-fs-shell-windows C:\ D:\

MCP client config (Claude Desktop / LM Studio mcp.json style):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "mcp-fs-shell-windows", "C:\\", "D:\\", "\\\\server\\share"]
    }
  }
}

The filesystem tools can only touch the passed directories (and anything under them). A root that cannot be accessed at startup logs a warning and is skipped; the server keeps running. Note that the shell tools are not root-restricted — see Security.

Build from source

For developers, or to run uncommitted changes:

git clone https://github.com/gerarddeluca/mcp-fs-shell-windows
cd mcp-fs-shell-windows
npm ci
npm run build
node dist\index.js <allowed-dir> [more-dirs...]

Then point your MCP config at node <path-to-repo>\dist\index.js with the allowed directories as the remaining args (same shape as the npx example above).

Filesystem tools (23)

Shell tools (8, Windows-only)

User commands are spawned as cmd.exe /d /c <command> with verbatim argv — quotes, redirects, and metacharacters arrive byte-for-byte (Node windowsVerbatimArguments), and /d skips AutoRun registry entries.

Practical notes:

• Background jobs live in an in-memory registry inside the server process: the table is lost on server restart, but job log files persist (under %TEMP%\mcp-fs-shell-windows\shell-jobs).

• timeout /t can fail when stdin is not an interactive console — use ping -n N 127.0.0.1 >nul for sleeps.

• Synchronous calls are bounded (max 28 s) so they cannot wedge the MCP request channel; anything longer should go through shell_start.

Docker

docker build -t mcp-fs-shell-windows .
docker run -i --rm -v /path/to/dir:/data mcp-fs-shell-windows /data

The filesystem tools work in the image; the shell tools require a Windows host with cmd.exe.

Differences from the base fork

v0.2.1 — official-server parity: head/tail reads (offset/limit in read_files), sizes in listings, overwrite in write_new_files, exact-match text editing (edit_files).

transfer_files (renamed from move_files): the canonical move/rename tool. Renamed because at least one MCP client (observed in LM Studio) silently drops tools named move_files/mv_files from the exposed tool list; transfer_files is registered last in the tools array.

Robustness patches:

• Missing/offline allowed roots warn at startup instead of exiting (NAS-down safe).

• validatePath walks to the nearest existing ancestor, so writes under brand-new nested directories work.

• ensureDirectoryExists at all mkdir sites (Node EPERM quirk on drive-root writes).

• Move-handler destination checks use errno ENOENT, so moves to fresh destinations succeed.

• zod pinned to ^3.23.8 (zod v4 breaks the SDK's schema conversion).

v0.2.2 — shell tools as listed above, with whole-process-tree kills and the detached interactive console window.

v0.2.4 — verbatim argv: windowsVerbatimArguments + /d on all user-command spawns (run/test/start and the terminal launcher).

Security

• The filesystem tools are confined to the allowed directories passed at startup (and their subtrees).

• The shell tools are not confined: anything the server process's user can execute will run, including against reachable network shares. Grant this server the same trust you would grant an unsandboxed shell.

• The server communicates over stdio and opens no network endpoints of its own.

License

MIT — see LICENSE. This project derives from MIT-licensed code (Anthropic, PBC; fabienvauchelles); all copyright notices are in the LICENSE file.