j0hanz/filesystem-context-mcp-server

**Let your AI assistant work with your files, safely.**
Read, search, edit, and patch files in the folders you choose.
Secret files stay hidden, and risky changes wait for your OK.
What is this?
Model Context Protocol (MCP) is how AI apps
such as Claude, GitHub Copilot in VS Code, and Cursor connect to tools.
Filesystem MCP is an MCP server: a small program that runs on your computer
and gives the AI 13 tools for working with files. You choose which folders it
can use, and everything outside them is off limits.
Once it is connected, you can ask things like:
- _"Find every TODO in this repo and group them by file."_
- _"Rename getUser to fetchUser in all .ts files. Show me the diff first."_
- _"What changed between config.dev.json and config.prod.json?"_
- _"Read the last 50 lines of server.log and explain the error."_
- _"Move the old screenshots into archive/2025/."_
Why Filesystem MCP?
- It is safe by default. The AI can use only the folders you allow, and
.env files, private keys, and cloud credentials are blocked. The server
asks you before the AI deletes a non-empty folder, opens a folder you did
not allow, or writes over a file with create or move. Only create and
copies can skip that question, by passing overwrite: true. Edits made with
edit, patch, and replace_text apply without asking, but the AI can
show you the diff first with dryRun. If the AI should never change
anything, --read-only removes every tool that writes.
- Search and editing are made for code. The AI can search inside files like
grep, with a regex engine (RE2) that cannot hang, and by default the
server skips .gitignored files and folders like node_modules. Edits are
exact-match replacements that return an error when the text does not match,
and you can preview them as a diff first.
- It saves the AI's context. The AI can read many files in one call or
only the lines it needs, and it can check a file's size and token estimate
before reading it.
- It works with any MCP client, over stdio or HTTP, on macOS, Linux, and
Windows. You can install it with npx, Docker, or a one-click Claude Desktop
extension, or build your own client on it.
- It is private. It runs on your machine, has no telemetry, and makes no
network calls.
Compared with the reference server
How this server differs from the official
@modelcontextprotocol/server-filesystem,
checked against its README on 2026-10-11:
| Capability | Filesystem MCP | Reference server |
| :------------------------ | :------------------------------------------------- | :-------------------------------------- |
| Search inside files | search_text: literal text or RE2 regex | None; search_files matches names only |
| Secret files | .env, keys, and credentials blocked by default | Not blocked |
| Overwriting a file | create asks you first (unless overwrite: true) | write_file overwrites without asking |
| Delete files | delete; asks before deleting a non-empty folder | None |
| .gitignore | Respected by listing and search tools | Not supported |
| Read-only mode | --read-only removes every tool that writes | Docker ro mounts only |
| Apply a unified diff | patch | None |
| Compare two files | diff | None |
| Replace across many files | replace_text over a folder or glob | None |
| Watch files | Subscribe to a file and get change notifications | None |
| Transport | stdio, or Streamable HTTP with --port | stdio |
Quick start
> [!NOTE]
> You need Node.js 24 or later. Check with node --version.
1. Add the server to your AI app. Pick yours below.
2. Replace /path/to/project with the folder the AI may use. You can list
several folders.
3. Restart the app and ask: _"Which folders can you access?"_
> [!TIP]
> VS Code currently shares the folders you have open with the server, so the
> one-click VS Code install works without a path. In other apps, or over HTTP,
> put the folder in args. If the AI says it has no folders, that is the fix.
VS Code
Click **Install in VS Code** above, or add this to .vscode/mcp.json: