filesystem-context-mcp-server

Purpose

Filesystem MCP is an MCP (Model Context Protocol) server used to let AI applications such as Claude, GitHub Copilot in VS Code, and Cursor safely operate on local files. It is a small program running on your own computer that provides the AI with 13 file operation tools. You choose which folders it is allowed to use, and anything outside those folders is inaccessible.

Main Capabilities

• Read, search, edit, and patch files, with support for reading multiple files at once, or reading only the lines you need; before reading, you can check file size and token estimates.
• Supports grep-like in-file search using the RE2 regex engine, so it will not hang because of a regex; by default it skips files ignored by .gitignore as well as directories such as node_modules, dist, and .git.
• Edits use exact-match replacement, and return an error when the text does not match; you can preview the diff first with dryRun.
• Supports reading and subscribing to arbitrary file resources in the format filesystem-mcp://file/{+path}; it also provides internal://instructions and the get-help prompt, which contains a server guide for models.

Security Mechanisms

• Secure by default: the AI can only use the folders you allow; .env files, private keys, cloud credentials, and similar items are blocked.
• When deleting a non-empty folder, opening an unauthorized folder, or overwriting a file with create or move, the server asks the user first; only create and copies can skip the prompt via overwrite: true.
• Edits from edit, patch, and replace_text are applied without prompting, but you can first show the diff with dryRun.
• If you want the AI to make no file modifications at all, use --read-only to remove all write-type tools.
• Privacy: runs entirely locally, with no telemetry, no analytics, no crash reports, and no outbound network requests.

Usage

Requires Node.js 24 or later; you can check with node --version.

Installation and integration methods:

• Install via npx: use the command arguments -y, @j0hanz/filesystem-mcp@latest, plus one or more folder paths.
• VS Code: click Install, or add the configuration to .vscode/mcp.json. VS Code currently shares the folders you already have open with the server, so its one-click install does not need paths; other applications or the HTTP method need folder paths in args.
• Cursor: after clicking Install, add folders to args, or write them into .cursor/mcp.json in the project, with the global configuration at ~/.cursor/mcp.json.
• Claude Desktop: download filesystem-mcp.mcpb, then open it with Claude Desktop and select the allowed folders; it runs with its built-in Node.js. You can also manually write claude_desktop_config.json (Settings → Developer → Edit Config), or install the extension and point it at the current project.
• Visual Studio: add the configuration to .vs\mcp.json in the solution folder, or to the global %USERPROFILE%.mcp.json.
• Docker: the container can only see the folders you mount. The provided example blocks writes twice through the :ro mount and the --read-only flag; remove both to allow the AI to modify files.
• Windsurf, Cline, and most clients use the same mcpServers JSON configuration as Claude Desktop.

After configuration is complete, restart the application and you can ask the AI: "Which folders can you access?" to confirm. If the AI says there are no available folders, adding folder paths to args will solve it.

Common configuration items: most people only need the folder arguments. 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 all flags and environment variables, the complete sensitive file list, limits, HTTP setup with API keys, Docker, and troubleshooting.

You can also install it globally and then run: filesystem-mcp /path/to/project.

Building your own client

You can have your own code (agents, editor plugins, web apps, CI tasks, or scripts) call Filesystem MCP, with the same rules as AI applications: code cannot access locations outside the allowed folders, nor can it read sensitive files.

• Data location: text blocks are written for the model; for tools that generate text themselves (list, search_text, edit, etc.), the same data is placed in _meta as JSON; the data for stat, create, and list_roots is placed in structuredContent. read is the exception: the file text is only in the text block, and _meta stores only its metadata.
• Paths: relative paths are resolved against the server's working directory when it is inside a root directory, otherwise against the root directory; when multiple root directories exist, the path must be located exactly under one of them. Absolute paths have no ambiguity. Search results are output relative to the root directory and can be passed back directly.
• Confirmation: overwriting, recursive deletion, and paths outside the root directories will prompt the user. You need to declare the elicitation capability and respond in the handler; or, under the 2026-07-28 protocol, receive it as data (input_required) and respond later.
• Protocol versions: the server supports the 2025 protocol and 2026-07-28, communicating via stdio and Streamable HTTP. Over HTTP, 2025-era clients will not receive confirmations or change notifications.

The client guide contains details tested with the TypeScript and Python SDKs, and the examples/ directory provides six runnable client examples.

Use cases

• Find all TODOs in a repository and group them by file.
• Rename getUser to fetchUser in all .ts files, viewing the diff first.
• Compare the differences between config.dev.json and config.prod.json.
• Read the last 50 lines of server.log and explain the error.
• Move old screenshots to archive/2025/.

Limitations

• Requires Node.js 24 or later.
• Can only access folders you explicitly allow; in container mode, only mounted folders are visible.
• When used over HTTP, 2025-era clients do not support confirmations and change notifications.
• Details for other platforms and clients, official comparison notes, and complete configuration: the materials point to the complete configuration reference and client guide, and are not expanded item by item here.