filesystem-mcp
by j0hanz
README.md
<img src="assets/logo.png" alt="Filesystem MCP logo" width="96" height="96">
# Filesystem MCP
**Let your AI assistant work with your files, safely.**
Read, search, edit, and patch files in the folders you choose.<br>
Secret files stay hidden, and risky changes wait for your OK.
[](https://www.npmjs.com/package/@j0hanz/filesystem-mcp) [](https://github.com/j0hanz/filesystem-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://github.com/j0hanz/filesystem-mcp/stargazers)
[](https://vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D&quality=insiders) [](https://vs-open.link/mcp-install?%7B%22filesystem-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D%7D) [](https://cursor.com/en/install-mcp?name=filesystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) [](https://github.com/j0hanz/filesystem-mcp/releases/latest/download/filesystem-mcp.mcpb)
## What is this?
[Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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 `.gitignore`d files and folders like `node_modules`. Edits are
exact-match replacements that fail loudly instead of guessing, and you can
preview them as a diff first.
- It goes easy on 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](#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`](https://github.com/modelcontextprotocol/servers/tree/main/src/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.
<details>
<summary><b>VS Code</b></summary>
Click **Install in VS Code** above, or add this to `.vscode/mcp.json`:
```json
{
"servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
}
}
}
```
Or from a terminal:
```sh
code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","/path/to/project"]}'
```
</details>
<details>
<summary><b>Cursor</b></summary>
Click **Install in Cursor** above, then add your folder to `args`. Or add this
to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for all
projects:
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
}
}
}
```
</details>
<details>
<summary><b>Claude Desktop</b></summary>
For a one-click install, download
[`filesystem-mcp.mcpb`](https://github.com/j0hanz/filesystem-mcp/releases/latest/download/filesystem-mcp.mcpb),
open it with Claude Desktop, and pick the folders to allow. Claude Desktop's
built-in Node.js runs it.
To set it up by hand, add this to `claude_desktop_config.json`
(Settings → Developer → Edit Config):
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
}
}
}
```
</details>
<details>
<summary><b>Claude Code</b></summary>
```sh
claude mcp add filesystem -- npx -y @j0hanz/filesystem-mcp@latest /path/to/project
```
Or install the plugin, which points the server at your current project:
```text
/plugin marketplace add j0hanz/j0hanz-marketplace
/plugin install filesystem-mcp@j0hanz-marketplace
```
</details>
<details>
<summary><b>Visual Studio</b></summary>
Add this to `.vs\mcp.json` in your solution folder, or `%USERPROFILE%\.mcp.json`
for all solutions:
```json
{
"servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest", "C:/path/to/project"]
}
}
}
```
</details>
<details>
<summary><b>GitHub Copilot CLI and Antigravity CLI (plugin)</b></summary>
The [filesystem-mcp plugin](https://github.com/j0hanz/j0hanz-marketplace/tree/main/plugins/filesystem-mcp)
sets the server up for your current project:
| Client | Install |
| :-------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| Copilot CLI | `copilot plugin marketplace add j0hanz/j0hanz-marketplace`, then `copilot plugin install filesystem-mcp@j0hanz-marketplace` |
| Antigravity CLI | `git clone https://github.com/j0hanz/j0hanz-marketplace`, then `agy plugin install ./j0hanz-marketplace/plugins/filesystem-mcp` |
</details>
<details>
<summary><b>Docker</b></summary>
The container can only see the folders you mount. This setup is read-only
twice over: the `:ro` mount and the `--read-only` flag.
```json
{
"mcpServers": {
"filesystem": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"/path/to/project:/workspace:ro",
"ghcr.io/j0hanz/filesystem-mcp:latest",
"--read-only",
"/workspace"
]
}
}
}
```
Drop `:ro` and `--read-only` to let the AI make changes. VS Code and Visual
Studio use `"servers"` instead of `"mcpServers"`. See
[Running in Docker](docs/configuration.md#running-in-docker) for more.
</details>
<details>
<summary><b>Other MCP clients</b></summary>
Windsurf, Cline, and most other clients use the same `mcpServers` JSON as
Claude Desktop above. In any client, the server is:
- **command:** `npx`
- **args:** `-y`, `@j0hanz/filesystem-mcp@latest`, then one or more folders
You can also install it globally and run `filesystem-mcp /path/to/project`:
```sh
npm install -g @j0hanz/filesystem-mcp
```
</details>
## Tools
| Tool | What it does |
| :--------------- | :------------------------------------------------------------------------------------------------------------ |
| `list_roots` | Shows the folders the server may use. |
| `list` | Lists a folder as a tree, like `ls` or `tree`. |
| `find_files` | Finds files by name or glob, such as `**/*.test.ts`. |
| `search_text` | Searches inside files for text or a regex, like `grep`, with optional context lines. |
| `stat` | Gets size, dates, type, permissions, and a token estimate without reading the file. |
| `read` | Reads one or many text files, whole or by line range, head, or tail. Images and audio come back as media. |
| `diff` | Compares two files and returns a unified diff. |
| `create` ✎ | Writes new files, or appends to them. Asks before replacing an existing file, unless `overwrite: true`. |
| `edit` ✎ | Replaces exact text in files. All edits to a file apply, or none do. `dryRun` shows the diff first. |
| `patch` ✎ | Applies a unified diff to a file. All hunks apply, or none do. |
| `replace_text` ✎ | Finds and replaces text or a regex across many files. `dryRun` shows what would change. |
| `move` ✎ | Moves, renames, or copies files and folders. Asks before overwriting, unless a copy passes `overwrite: true`. |
| `delete` ✎ | Deletes files and folders. Asks before deleting a non-empty folder. |
✎ changes files. `--read-only` removes these tools.
Search and listing tools skip hidden files, `.gitignore`d files, and folders
like `node_modules`, `dist`, and `.git` unless the AI asks for them.
## Configuration
Most people only need the folder argument. These options cover the common
cases:
| Option | What it does |
| :-------------------- | :--------------------------------------------------------------------------- |
| `--read-only` | Removes every tool that changes files. |
| `--deny '<pattern>'` | Blocks more files, for example `--deny 'private/**'` or `--deny '*.sqlite'`. |
| `--allow '<pattern>'` | Unblocks one built-in secret pattern, for example `--allow '.env.example'`. |
| `--allow-cwd` | Also allows the folder the server was started from. |
| `--max-file-size <n>` | Largest file `read` will load, in bytes. Default 10 MiB. |
| `--port <n>` | Serves over HTTP at `http://127.0.0.1:<n>/mcp` instead of stdio. |
| `--print-config` | Prints the settings the server would use, then exits. |
Flags go in `args` after the package name, for example
`["-y", "@j0hanz/filesystem-mcp@latest", "--read-only", "/path/to/project"]`.
The [full configuration reference](docs/configuration.md) covers every flag
and environment variable, the complete secret-file list, limits, HTTP setup
with API keys, Docker, and troubleshooting.
## Security
| Protection | How it works |
| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Folder sandbox | The server resolves every path, including symlinks, and the resolved path must stay inside an allowed folder. |
| Secret files | `.env`, `*.pem`, `*.key`, SSH keys, `.npmrc`, cloud credentials, and [more](docs/configuration.md#secret-files) are blocked and hidden from listings. |
| You stay in charge | The server asks you before the AI deletes a non-empty folder, gets access to a new folder, or writes over a file with `create` or `move`. Only `create` and copies skip that question, when the AI passes `overwrite: true`. In-place edits (`edit`, `patch`, `replace_text`) do not ask, but `dryRun` previews them. A client that cannot ask gets a clear error instead. |
| Off-limits folders | Neither the AI nor the client can ever add your home folder itself, system folders, or `~/.ssh`, `~/.aws`, and similar folders. |
| Safe writes | New content goes to a temporary file that is then renamed into place, so a crash never leaves a half-written file. Writes keep the file's permissions. |
| No regex hangs | RE2 runs in linear time, so no search pattern can freeze the server. |
| HTTP | The server listens only on localhost by default. Any other address requires an API key. |
| Container | The Docker image runs as a non-root user. |
If you find a vulnerability, please report it privately.
[SECURITY.md](SECURITY.md) explains how.
## Build your own client
You can also call Filesystem MCP from your own code: an agent, an editor
plugin, a web app, a CI job, or a script. The same rules apply as for an AI
app, so your code cannot reach outside the allowed folders or read secret
files.
```ts
import { Client } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
const dir = '/path/to/project';
const client = new Client(
{ name: 'my-app', version: '1.0.0' },
{ capabilities: { elicitation: { form: {} } }, versionNegotiation: { mode: 'auto' } },
);
client.setRequestHandler('elicitation/create', async () => ({ action: 'decline' }));
await client.connect(
new StdioClientTransport({
command: 'npx',
args: ['-y', '@j0hanz/filesystem-mcp', dir],
cwd: dir,
}),
);
const result = await client.callTool({ name: 'search_text', arguments: { searchPattern: 'TODO' } });
const { matches } = (result.structuredContent ?? result._meta) as { matches: unknown[] };
console.log(matches);
await client.close(); // stops the server process; without it the script never exits
```
The basics:
- **Where the data is.** The text block is written for a model. The same data
as JSON is in `_meta` for tools that write their own text (`list`,
`search_text`, `edit`, ...) and in `structuredContent` for `stat`,
`create`, and `list_roots`. `read` is the exception: the file's text is
only in the text block, and `_meta` holds metadata about it.
- **Paths.** Relative paths resolve against the server's working directory,
not its root: set `cwd` over stdio, and send absolute paths over HTTP.
- **Confirmations.** Overwrites, recursive deletes, and paths outside the
roots are questions for the user. Declare the `elicitation` capability and
answer them in a handler, or, on the 2026-07-28 protocol, take them as data
(`input_required`) and answer later.
- **Protocol versions.** The server speaks the 2025 protocol and 2026-07-28,
over stdio and Streamable HTTP. Over HTTP, 2025-era clients get no
confirmations or change notifications.
- **Resources.** Read and subscribe to any file as
`filesystem-mcp://file/{+path}`; `internal://instructions` and the
`get-help` prompt hold the server's guide for models.
The [client guide](docs/client-guide.md) has the details, tested with the
TypeScript and Python SDKs, and [`examples/`](examples/) has six runnable
clients:
| Example | What it is |
| :----------------------------------------- | :------------------------------------------------------------------ |
| [fsq](examples/clients/fsq/) | Any tool from your shell, over stdio or HTTP; `--json` for scripts |
| [browser](examples/clients/browser/) | A local web UI where the server's questions appear in the page |
| [tail](examples/clients/tail/) | `tail -f` through file subscriptions, locally or on a remote server |
| [gatekeeper](examples/clients/gatekeeper/) | A coding agent that shows each change's diff and waits for your y/N |
| [hooks](examples/clients/hooks/) | Runs a task through a model whenever the workspace changes |
| [python](examples/clients/python/) | A TODO report for a workspace, with the Python SDK |
## Privacy Policy
Filesystem MCP runs entirely on your machine. This policy covers the npm
package, the Docker image, and the `.mcpb` desktop extension.
- **Data collection:** none. The server has no telemetry, analytics, or crash
reporting, and makes no outbound network requests.
- **Use and storage:** files are read and written only inside the folders you
allow, and only when your MCP client calls a tool. Tool results go to that
client and nowhere else. Short-lived result caches live in memory and
disappear when the server exits.
- **Third-party sharing:** none by this server. Your MCP client may send tool
results to its model provider under that client's own privacy policy.
- **Retention:** nothing is kept after the process exits. Diagnostic logs go to
stderr on your machine; your MCP client may save them in its own log files.
- **Contact:** open an issue at
<https://github.com/j0hanz/filesystem-mcp/issues>, or report security
problems privately through
[GitHub Security Advisories](https://github.com/j0hanz/filesystem-mcp/security/advisories).
## Contributing
Bug reports, ideas, and pull requests are welcome. Start with
[CONTRIBUTING.md](CONTRIBUTING.md): it covers setup, running the server from
source, and the checks a pull request needs.
If Filesystem MCP is useful to you, a star on GitHub helps other people find it.
[](https://github.com/j0hanz/filesystem-mcp/graphs/contributors)
## License
[MIT](LICENSE)
TDQS
A4.2/5.0
Scored across 13 tools
Disambiguation5/5
Each tool targets a clearly distinct file operation (read, write, edit, diff, patch, search, metadata) with explicit cross-references in the descriptions. Overlaps like edit vs replace_text are well delineated by exact-match uniqueness vs global replacement.
Naming Consistency5/5
All names use consistent snake_case with imperative verbs (create, delete, list, read, move, stat, etc.). Multi-word names like replace_text, search_text, and find_files follow the same verb_noun pattern.
Tool Count5/5
13 tools is well-scoped for a filesystem server, covering essential operations without redundancy. Each tool earns its place by handling a specific action or resource.
Completeness4/5
Core file lifecycle (create, read, update, delete, move, list, search, diff, stat) is well covered, with parent directory creation handled implicitly. Minor gaps remain for permission changes (chmod/chown) and link creation, but agents can work around most needs.
Maintenance
ActivityActive
ResponsivenessWithin a week