@j0hanz/filesystem

GitHub Actions

Filesystem MCP server for AI assistants. Search, read, edit, and manage local files in directories you choose.

Add to Cursor Add to VS Code Run on PlugMCP

1{2  "mcpServers": {3    "j0hanz-filesystem-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "@j0hanz/[email protected]"8      ]9    }10  }11}

.cursor/mcp.jsonMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @j0hanz/[email protected]

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add j0hanz-filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@2.11.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "j0hanz-filesystem-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "@j0hanz/[email protected]"8      ]9    }10  }11}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 2.11.0
Last checked: 2026-10-28

Stars: —
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install @j0hanz/filesystem?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does @j0hanz/filesystem need an API key?

No required environment variable is listed on this record.

What transport does @j0hanz/filesystem use?

@j0hanz/filesystem runs locally over stdio.

When was @j0hanz/filesystem last checked?

Last checked 2026-10-28. Filesystem MCP server for AI assistants. Search, read, edit, and manage local files in directories you choose.

From the publisher

Documentation

Filesystem MCP

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 14 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.

Add the server to your AI app. Pick yours below.
Replace /path/to/project with the folder the AI may use. You can list several folders.
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.

Click Install in VS Code above, or add this to .vscode/mcp.json:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Or from a terminal:

code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","/path/to/project"]}'

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:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

For a one-click install, download filesystem-mcp.mcpb, open it with Claude Desktop, and pick the folders to allow. Claude Desktop's built-in Node.js runs it. The extension's settings also let you turn on read-only mode and block more files.

To set it up by hand, add this to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

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:

/plugin marketplace add j0hanz/j0hanz-marketplace
/plugin install filesystem-mcp@j0hanz-marketplace

Add this to .vs\mcp.json in your solution folder, or %USERPROFILE%\.mcp.json for all solutions:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "C:/path/to/project"]
    }
  }
}

The filesystem-mcp plugin 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`

The container can only see the folders you mount. This setup blocks writes twice, with the :ro mount and with the --read-only flag.

{
  "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 for more.

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:

npm install -g @j0hanz/filesystem-mcp

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 text files whole or by lines, head, or tail. Images and audio come back as media; others with `binary`.
`diff`	Compares two files and returns a unified diff.
`create` ✎	Writes new files, appends, or makes empty folders. Asks before replacing a 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.
`undo` ✎	Reverts earlier changes by undo id or the last N calls, while the server runs. Skips files changed since.

✎ changes files. --read-only removes these tools.

Search and listing tools skip hidden files, .gitignored 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 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 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 an 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 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.

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. A relative path resolves against the server's working directory when that is inside a root, and against the root otherwise. With several roots, it must exist under exactly one of them. Absolute paths are never ambiguous. Search results are printed relative to the root, so a result can be passed straight back. A name that differs from the one on disk only in Unicode form (NFC or NFD) or in its space characters (U+00A0, U+202F) finds that entry.
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 has the details, tested with the TypeScript and Python SDKs, and examples/ has six runnable clients:

Example	What it is
fsq	Any tool from your shell, over stdio or HTTP; `--json` for scripts
browser	A local web UI where the server's questions appear in the page
tail	`tail -f` through file subscriptions, locally or on a remote server
gatekeeper	A coding agent that shows each change's diff and waits for your y/N
hooks	Runs a task through a model whenever the workspace changes
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: the server reads and writes files 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 and the undo history (saved file contents) 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: the server keeps nothing 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.

Contributing

Bug reports, ideas, and pull requests are welcome. Start with 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.

License

MIT

@j0hanz/filesystem

GitHub Actions

Filesystem MCP server for AI assistants. Search, read, edit, and manage local files in directories you choose.

Devops Developer Tools

Add to Cursor Add to VS Code Run on PlugMCP

GitHub npm Website

Add to Cursor Add to VS Code Run on PlugMCP

1{2  "mcpServers": {3    "j0hanz-filesystem-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "@j0hanz/[email protected]"8      ]9    }10  }11}

.cursor/mcp.jsonMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @j0hanz/[email protected]

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add j0hanz-filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@2.11.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "j0hanz-filesystem-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "@j0hanz/[email protected]"8      ]9    }10  }11}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 2.11.0
Last checked: 2026-10-28

Stars: —
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install @j0hanz/filesystem?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does @j0hanz/filesystem need an API key?

No required environment variable is listed on this record.

What transport does @j0hanz/filesystem use?

@j0hanz/filesystem runs locally over stdio.

When was @j0hanz/filesystem last checked?

Last checked 2026-10-28. Filesystem MCP server for AI assistants. Search, read, edit, and manage local files in directories you choose.

From the publisher

Documentation

Filesystem MCP

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?

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.

Add the server to your AI app. Pick yours below.
Replace /path/to/project with the folder the AI may use. You can list several folders.
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.

Click Install in VS Code above, or add this to .vscode/mcp.json:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Or from a terminal:

code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","/path/to/project"]}'

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:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

To set it up by hand, add this to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

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:

/plugin marketplace add j0hanz/j0hanz-marketplace
/plugin install filesystem-mcp@j0hanz-marketplace

Add this to .vs\mcp.json in your solution folder, or %USERPROFILE%\.mcp.json for all solutions:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "C:/path/to/project"]
    }
  }
}

The filesystem-mcp plugin 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`

The container can only see the folders you mount. This setup blocks writes twice, with the :ro mount and with the --read-only flag.

{
  "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 for more.

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:

npm install -g @j0hanz/filesystem-mcp

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 text files whole or by lines, head, or tail. Images and audio come back as media; others with `binary`.
`diff`	Compares two files and returns a unified diff.
`create` ✎	Writes new files, appends, or makes empty folders. Asks before replacing a 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.
`undo` ✎	Reverts earlier changes by undo id or the last N calls, while the server runs. Skips files changed since.

✎ changes files. --read-only removes these tools.

Search and listing tools skip hidden files, .gitignored 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 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 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 an 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 explains how.

Build your own client

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. A relative path resolves against the server's working directory when that is inside a root, and against the root otherwise. With several roots, it must exist under exactly one of them. Absolute paths are never ambiguous. Search results are printed relative to the root, so a result can be passed straight back. A name that differs from the one on disk only in Unicode form (NFC or NFD) or in its space characters (U+00A0, U+202F) finds that entry.
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 has the details, tested with the TypeScript and Python SDKs, and examples/ has six runnable clients:

Example	What it is
fsq	Any tool from your shell, over stdio or HTTP; `--json` for scripts
browser	A local web UI where the server's questions appear in the page
tail	`tail -f` through file subscriptions, locally or on a remote server
gatekeeper	A coding agent that shows each change's diff and waits for your y/N
hooks	Runs a task through a model whenever the workspace changes
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: the server reads and writes files 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 and the undo history (saved file contents) 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: the server keeps nothing 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.

Contributing

Bug reports, ideas, and pull requests are welcome. Start with 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.

License

MIT