Filesystem Context MCP Server

What j0hanz/filesystem-context-mcp-server MCP server does

The j0hanz/filesystem-context-mcp-server MCP server exposes selected local directories to MCP-compatible AI clients. It can inspect project structure, locate files, read text, search contents, compare files, and retrieve metadata. It also provides mutation tools for creating, editing, moving, copying, replacing, patching, and deleting files.

Access is restricted to workspace roots supplied when the process starts. Path validation applies to every operation, and sensitive filename patterns including .env, *.pem, and names containing id_rsa are denied by default. This makes the server suitable for giving an agent access to a project directory while keeping unrelated parts of the host outside its scope.

How it works

The server communicates over MCP using stdio unless a port is supplied to enable Streamable HTTP. Clients should call list_roots first; subsequent filesystem tools operate within the roots returned by that call. Many operations support batches through arrays such as paths[] or files[].

Search operations use RE2 through re2-wasm. Its supported regular-expression model is designed for linear-time matching and does not provide lookahead, lookbehind, or backreferences. File subscriptions can send change notifications for watched resources.

Tools and capabilities

Navigation and discovery tools include list_roots, list, and find_files. Inspection tools include stat, search_text, diff, and read. The read operation supports head and tail reads, line ranges, and batches of paths.

Write-capable tools are create, edit, move, delete, replace_text, and patch. edit performs sequential literal replacements and accepts up to five files per call. move can rename or copy files and directories, while patch applies a unified diff to one file. Deletion is permanent.

Setup and configuration

The package requires Node.js 24 or newer and is distributed through npm. A typical launch uses npx -y @j0hanz/filesystem-mcp followed by one or more allowed directory paths. The same package can be installed globally and started with the filesystem-mcp executable. Docker is also supported, including mounts that can be made read-only.

Claude Desktop and Cursor configurations use an MCP server entry with the npx command and the package name. The repository also documents configuration for VS Code and Visual Studio. Docker users can combine a read-only volume mount with the server's --read-only option.

Limitations and notes

The j0hanz/filesystem-context-mcp-server MCP server is not unrestricted filesystem access: roots must be configured, and blocked filename patterns remain unavailable unless the server's documented configuration changes them. Its default transport is local stdio; HTTP use requires starting it with a port. The runtime requirement is Node.js 24 or later.

The read-only mode removes create, edit, move, delete, patch, and replace_text from the advertised tool list. This is separate from an operating-system-level read-only container mount, so both controls can be used together. The project is licensed under MIT.