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

**Category:** 📂 File Systems  
**Repository:** https://github.com/j0hanz/filesystem-context-mcp-server  
**GitHub Stars:** 32  
**npm Downloads (last month):** 7864  
**Views:** 4  
**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:

- **create** — Write whole text files (new, overwrite, or append) and create empty directories, with missing parents. Use when you have full content or need folders. Do not use it for partial edits; use `edit`, `replace_text`, or `patch` instead, and `move` to copy or rename. Whole-file writes are atomic (temp file, then rename); appends are not. An existing file is replaced only with overwrite: true or after one user confirmation for the batch; nothing is written before the answer. Declined entries fail with CANCELLED; skipped ones land in skipped. Entries fail alone; the call errors only when all fail. Returns files (path, size, lineCount, mimeType, kind, resourceUri, created, modified), directories, failures, skipped, and an undo id for `undo` (30 min), or undoUnavailable.
- **delete** — Delete files, directories, and symlinks. Use when a path should no longer exist. Do not use it to rename or relocate; use `move` instead, and `undo` to restore. A symlink is removed, never its target. A non-empty directory needs `recursive: true`; without it, that path fails INVALID_INPUT. With it, the user must confirm. Nothing is deleted until every prompt is answered. A client that cannot prompt fails the whole call INVALID_INPUT. Deleting a folder that holds protected files cannot be undone. Other failures hit only their own path: ACCESS_DENIED for a root, read-only, or outside path; CANCELLED when refused or changed; INVALID_INPUT for a nested pair. Returns per-path { deleted } or { error } (a skipped prompt gives deleted: false), a summary, and an undo id valid 30 minutes, or undoUnavailable with the reason.
- **diff** — Compare two text files and return a unified diff from a to b. Use when you need line differences between two files on disk. Do not use it to find text across files; use `search_text` instead. To preview your own pending change, use the dryRun option of the write tools. Binary and non-UTF-8 files fail. A file over the size limit fails with TOO_LARGE. So does a diff not done within 1 s, or a full diff queue; retry once, then `read` matching line ranges. Returns ---/+++ headers (basenames) and @@ hunks; identical files give headers only.
- **edit** — Replace exact, unique text snippets in up to 5 existing text files. Use when you know the exact text to change. Do not use it for every match of a pattern; use `replace_text` instead. To apply a unified diff, use `patch`; for a new file or a whole rewrite, use `create`. Each file is all or nothing: an unmatched or ambiguous oldText writes nothing to that file, and other files still run; dryRun reports unmatched text instead of failing. An oldText with no exact match is retried ignoring indentation and spacing and applied only if that matches once; the summary says so. Missing, binary, non-UTF-8, and over-size-cap (default 10 MiB) files fail. Returns one summary line per file (+added -removed, NO MATCH, or FAILED); a dry run or returnDiff appends unified diffs. With undo enabled, live runs add an undo id for `undo`, valid 30 minutes.
- **list** — List a directory inside the roots as a name tree, walking up to maxDepth levels. Use when you need to see what a folder holds. Do not use it to find files by name or glob; use `find_files` instead, `read` or `search_text` for contents, `stat` for one path. Skips hidden entries, .gitignore matches, and build and tool folders unless includeHidden or includeIgnored is set, naming the ignore-rule folders it hid. At most 20,000 entries are kept. A timeout returns a partial result with stoppedReason. Errors: NOT_DIRECTORY for a file, ACCESS_DENIED outside the roots. Returns tree text, entries[{name, relativePath, type, size?}], totals, unexpandedDirectories, and skippedInaccessible. A cut result adds nextCursor (about 5 min) and resourceUri (about 60 s).
- **move** — Move, rename, or copy files and directories inside the roots. Use when you need to rename, relocate, or duplicate (copy: true). Do not use to change contents (`edit`, `patch`) or remove paths (`delete`). Missing parents are created. An existing destination asks to confirm; declining cancels the call, skipping drops that pair. Only copies can bypass the prompt (overwrite: true). A directory move never merges into a non-empty directory; a copy merges. Pairs that share a destination or overlap another pair fail; run dependent moves separately. Returns a summary line per pair and failure, plus moves[{ from, to }], failures?, skipped?, and an undo id for `undo` (30 minutes) or undoUnavailable. The call is an error only if every pair failed.
- **patch** — Apply a single-file unified diff to one existing UTF-8 text file. Use when you hold a unified diff. Do not use it for one exact snippet; use `edit` instead. For pattern matches use `replace_text`; for new files, `create`. All or nothing: if any hunk mismatches its context, nothing is written; INVALID_INPUT usually names it. Header line numbers may be off. A diff of context lines only writes nothing and records no undo. File lines x diff lines over 10,000,000 fails with TOO_LARGE. Returns path, linesAdded, linesRemoved, size, lineCount, mimeType, kind, modified, resourceUri when linkable, and an undo id for `undo` (30 minutes) or undoUnavailable; dryRun adds the resulting diff.
- **read** — Read one file or up to 1000, whole or as a line slice. Use when you know the path. Do not use it to check size or existence; use `stat` instead. To locate content, use `search_text`, `find_files`, or `list`. Only whole reads return images and audio as media; other binary files fail with BINARY_FILE unless binary: true. Pick one slice (head, tail, or startLine/endLine); it applies to every batch file. Past the size limit: a single-path whole read returns its first 2000 lines (up to 256 KiB) with continuation args; a head or range is truncated; a batch file fails TOO_LARGE. UTF-16 text with a byte-order mark is returned decoded, with encoding set; past the size limit it fails TOO_LARGE in every mode. A batch shares a 512 KiB budget: an overflowing file is skipped and later files still read. isError means every path failed. Returns text plus per-path results[]: an error, or linesRead, hasMoreLines, continuation args, modified, optional contentHash. Full reads add totalLines; a tail gets no continuation.
- **replace_text** — Replace every match of literal text or an RE2 regex in one file or across a directory tree. Use when the same change must land at every occurrence. Do not use it for one unique snippet; use `edit` instead, `patch` for a unified diff, or `search_text` to only find matches. A live run rewrites each file as the scan reaches it; one failed file does not stop the others. Reaching maxMatches (default 100), maxFiles, or the deadline stops the run; files already rewritten stay changed. Returns changed paths, failures, skip counts, stoppedReason, and an undo id (live runs, when undo is enabled) for `undo`, valid 30 minutes. isError is set when every file failed or the request is invalid (bad regex, path outside roots).
- **list_roots** — List roots this server can access and its read-only directories. Use for allowed paths or after ACCESS_DENIED. Do not use it to browse; use `list`, `find_files`, or `stat` instead. Accepted grants add roots; call again after one. Outside paths prompt a grant only on elicitation clients, never for home, system paths, or anything outside FS_ROOT_BOUNDARY. Returns absolute { roots, readOnlyDirs (writes, moves, deletes refused), hint? when roots is empty }.
- **search_text** — Search file contents under the roots for literal text or an RE2 regex. Use when you need the files and lines that contain some text. Do not use it to find files by name; use `find_files` instead. A regex may span lines; the hit is on its first line. Skips hidden entries, .gitignore matches, and build folders unless includeHidden or includeIgnored. Lines over 1000 chars are clipped around the match. Stops early at 10000 matching lines or the timeout, setting stoppedReason. Returns root, `file:line: text` rows (a named file prints its path once), matches with column and context, totals, and skip counts. A multi-page or stopped first page also returns nextCursor, valid about 5 min after its last page, and resourceUri, valid about 60 s.
- **find_files** — Find files whose name or path matches a glob under a directory. Use when you know a name or path pattern but not the location. Do not use it for file contents; use `search_text` instead. To browse a folder, use `list`. Matches files; type: "directory" or "any" also matches directories. Skips hidden entries, .gitignore matches, and build folders unless includeHidden or includeIgnored. Scanning stops at 10,000 matches (stoppedReason maxResults) or the time limit (FS_TOOL_TIMEOUT_MS, default 5 s; stoppedReason timeout) and still returns what it found. path must be an existing directory; a file path is rejected. maxResults sizes a page, not the scan; page on with nextCursor. Returns root, results[{ path }], totalMatches, and filesScanned. When set, it adds nextCursor, stoppedReason, skippedInaccessible, excludedDirs (total and first 5), and resourceUri (all kept matches). Paths are relative to root when unambiguous, otherwise absolute.
- **stat** — Get metadata for files or directories. Use when you need to check existence, size, or read cost. Do not use for contents; use `read` instead, `list` for directory entries, or `find_files` to find by name. Pass `path` or `paths` (up to 1000). Paths settle independently (missing gives NOT_FOUND); the call errors only if all fail. Symlinks report their own metadata, not the target's. `path` gives one result; `paths` gives one per path, in input order. Returns per-path values or errors ({ code, message }), plus summary { total, succeeded, failed }. Values hold name, path, type, size or entryCount (directories), tokenEstimate (files, bytes/4), lineCount (text files up to 256 KiB, in calls of up to 20 paths), timestamps, permissions (POSIX) or readOnly (Windows), isHidden (dot prefix), hardLinks (a file with other names; a write changes them all), mimeType, symlinkTarget.
- **undo** — Revert create, edit, replace_text, patch, move, or delete calls by undo id or the newest N calls. Use when a change made by this server must be reverted. Do not use for outside changes or expired ids; rewrite those with `edit` or `create`. Preview with dryRun, which lists ids. A path changed since that call is skipped while the rest revert; it stays under its id for a retry. The in-memory journal keeps up to 64 calls for 30 minutes, fewer when FS_MAX_UNDO_BYTES fills. No redo. Unknown ids fail NOT_FOUND. Returns steps[] of {id, tool, results[]}, each path restored or with an error code. A long list is cut (failures kept), marked truncated with totalResults. Errors only if every path fails.

## 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@latest"]
  }
}
```

## Documentation

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

j0hanz/filesystem-context-mcp-server gives MCP-compatible AI applications controlled access to local folders for filesystem exploration and analysis. It is intended for read-only workflows: agents can discover files, inspect their contents and metadata, search across a project, and compare two files without changing them.

Access is limited to folders configured for the server. Symlink protection helps prevent directory traversal from escaping the allowed filesystem scope. The server exposes the folders it can use through `list_roots`, so an agent can establish its available scope before inspecting files.

## How it works

The server runs locally and communicates with an AI client through MCP. Configure one or more permitted folder paths, then connect the client to the server process. Requests are handled through focused filesystem tools rather than unrestricted shell access.

Directory exploration uses `list`, which returns a tree-style view of a folder. `find_files` accepts file names or glob patterns, while `search_text` searches file contents using literal text or a regular expression and can include surrounding context lines. Before reading a large file, `stat` can report its size and an estimated token count.

`read` can return an entire text file or selected lines, including the beginning or end of a file. Images and audio are returned as media; other non-text content is represented as binary data. `diff` compares two files and returns a unified diff.

## Setup and configuration

Node.js 24 or later is required. The package can be started with `npx`, using the `@j0hanz/filesystem-mcp@latest` package reference and one or more folder paths as arguments. Replace the example path with a directory the agent should be allowed to inspect.

A typical stdio configuration uses a command such as `npx` with these arguments:

- `-y`
- `@j0hanz/filesystem-mcp@latest`
- One or more permitted folder paths

The server can also be used over Streamable HTTP by starting it with a port option. Claude Desktop offers a downloadable extension, while VS Code and Cursor provide MCP installation links and configuration examples.

## Tools and capabilities

- `list_roots`: Shows the folders available to the server.
- `list`: Produces a tree-style listing for a folder.
- `find_files`: Matches files by name or glob pattern.
- `search_text`: Searches file contents with text or regular expressions and optional context.
- `stat`: Returns file size, timestamps, type, permissions, and a token estimate without reading the file.
- `read`: Reads complete files or selected lines and returns supported media appropriately.
- `diff`: Generates a unified comparison between two files.

## Limitations and notes

Only configured folders are available to the agent, and symlink protection limits traversal through filesystem links. The server is suitable for inspection and comparison rather than file modification. Reading very large files may consume substantial context, so `stat`, line ranges, head, tail, and targeted searches can help constrain responses. Node.js 24 or newer is needed to run the package.

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

