# j0hanz/filesystem-context-mcp-server [Health: Active]

**Category:** 📂 File Systems  
**Repository:** https://github.com/j0hanz/filesystem-context-mcp-server  
**GitHub Stars:** 15  
**npm Downloads (last month):** 1366  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/j0hanz-filesystem-context-mcp-server

## Description
Read-only MCP server for secure filesystem exploration, searching, and analysis with symlink protection.

## Tools
Capabilities this server exposes over MCP:

- **list_roots** — List allowed workspace roots. Call this first — all other tools scope to these.
- **list** — List directory contents. Returns entries (dirs-first, alphabetical) and an ASCII tree.
- **find_files** — Find files by glob pattern (e.g. `**/*.ts`). Returns matching files with metadata.
- **stat** — Get file/directory metadata: size, modified time, permissions, MIME type, token estimate.
- **search_text** — Search file contents for text (grep-like). Returns matching lines with context.
- **diff** — Compare two files and return a unified diff with added/removed line counts.
- **read** — Read a text file. Supports head/tail and line ranges. Accepts `paths[]` for batches.
- **create** — Create one or more files, overwriting existing content and creating parent directories as needed.
- **edit** — Apply sequential literal string replacements to one or more files (max 5 per call).
- **move** — Move, rename, or copy (`copy: true`) one or more files/directories to explicit destinations.
- **delete** — Permanently delete one or more files or directories. This action is irreversible.
- **replace_text** — Bulk search-and-replace across files matching a glob pattern.
- **patch** — Apply a single-file unified diff and write the result.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "filesystem-context-mcp-server": {
    "command": "npx",
    "args": ["-y","@j0hanz/filesystem-mcp"]
  }
}
```

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/j0hanz-filesystem-context-mcp-server/readme_