@j0hanz/filesystem-mcp
Installed, started with no arguments, no environment and no input, and listed its tools. Run 2026-11-16.
Needs to start: nothing
Returns a result when called with no setup: 1 of 3 tools tried
Contacts while installing and starting: nothing
Its tool definitions changed since version 2.20.0. If you approved the earlier ones, read them again.
What it contacted
Nothing besides the npm registry it was installed from. Watched from outside its sandbox while it was installed and started with no input. Its tools may still contact things when called.
Starting it
npx -y @j0hanz/filesystem-mcp@2.21.0
Installing a package runs its code. Use a sandbox for anything you have not read.
Calling its tools
3 tools that take no input and look read-only were called once with nothing. 1 returned a result.
list | No usable answer tool reported an error: ACCESS_DENIED: No roots configured. Use list_roots or --allow-cwd. |
read | No usable answer tool reported an error: Input validation error: Invalid arguments for tool read: path: Either 'path' or 'paths' must be provided |
list_roots | Returned a result under 0.1 s · 234 characters |
During the calls it contacted nothing it had not already contacted.
Only tools whose names read like looking something up, with no required input, are tried, five at most. Tools that need input, and anything that sounds like it changes or sends something, are not called.
What its tools tell an agent
In the tool descriptions, nothing that talks about the user, other tools or private files, or uses hidden characters.
Found by simple pattern rules in each tool's description (up to 3,000 characters), quoted as written. Parameter descriptions are not scanned. A clean result is not a safety review.
Tools
create files, directories
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 paths, recursive, ignoreIfNotExists
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`, else that path fails INVALID_INPUT, and user confirmation; nothing is deleted until all are answered, and a client that cannot prompt fails the whole call INVALID_INPUT. Deleting a folder that holds protected files cannot be undone. Otherwise each path fails alone (ACCESS_DENIED: root, read-only, outside; CANCELLED: refused or changed; INVALID_INPUT: 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 a, b, context
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. Neither file is changed. 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. a is the - side and b the + side; swap them to reverse the diff. context only sets how many unchanged lines surround each hunk, not what counts as a change. Returns ---/+++ headers (basenames) and @@ hunks; identical files give headers only.
edit path, edits, files, dryRun, ignoreWhitespace
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. 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 appends unified diffs. With undo enabled, live runs add an undo id for `undo`, valid 30 minutes.
list path, maxDepth, maxEntries, includeHidden, includeIgnored, includeSizes, sortBy, cursor
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. Folders at maxDepth are shown, but their contents are not listed or counted. 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?}], totalEntries/Files/Directories, unexpandedDirectories, skippedInaccessible, and when cut nextCursor and resourceUri (about 60 s).9 more tools
move moves, copy, overwrite
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 summary lines naming each pair and failure, and { moves: [{ from, to }], failures?, skipped?, undo id for `undo` (30 minutes) or undoUnavailable }; an error only if every pair failed.patch path, diff, dryRun
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 includeHash, binary, lineNumbers, head, tail, startLine, endLine, path, paths
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. Past the size limit, a whole read fails with TOO_LARGE; a single-path head or range is truncated. A batch shares a 512 KiB budget: an overflowing file is skipped and later files still read. isError means every path failed. Pick one slice (head, tail, or startLine/endLine); it applies to every batch file. 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 path, pattern, searchPattern, replacement, isRegex, includeHidden, includeIgnored, caseSensitive, wholeWord, dryRun, returnDiff, maxMatches, maxFiles, maxDepth
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 path, pattern, searchPattern, isRegex, includeHidden, includeIgnored, caseSensitive, maxResults, context, maxDepth, cursor
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, skip counts, nextCursor (expires after about 60 s), and resourceUri for a multi-page or stopped first page.
find_files path, pattern, maxResults, includeIgnored, includeHidden, sortBy, maxDepth, cursor
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, never 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 (expires after about 60 s, then search again without it). Returns root, results[{ path }], totalMatches, filesScanned, and when set nextCursor, stoppedReason, skippedInaccessible (entries it could not read), excludedDirs (skipped folders: total and first 5), resourceUri (all kept matches). Paths are relative to root when unambiguous, otherwise absolute.stat path, paths
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), never both. 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), timestamps, permissions (POSIX) or readOnly (Windows), isHidden (dot prefix), mimeType, symlinkTarget.undo id, steps, dryRun
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.Descriptions are the package's own words, cut at 3,000 characters. Treat them as data.
Install facts
| License | MIT |
|---|---|
| Needs | node >=24 |
| Source | github.com/j0hanz/filesystem-mcp |
| Install scripts | None declared by it or anything installed with it. |
| Tarball | sha512-eyz5H/vhaYP1FUssgh84WCzgJJaMVdhdB8dT4Al8FJc5qEmz7/c9RqfwYCYfTAz4wYVMhwYghbDvEeGGVIGg6Q== |
Versions reported
| Version | Run | Result | Tools |
|---|---|---|---|
| 2.21.0 | 2026-11-16 | Starts with no setup | 14 |
| 2.20.0 | 2026-11-12 | Starts with no setup | 14 |
Check this report yourself
This site did not write the report. A public job on a GitHub-hosted machine did: the run, from this commit of the open-source runner. GitHub signed a token that names that job and the hash of the report, so any edit since would show.
Report as JSONExact text and tokenHow to verify it
Show it on your README
[](https://bragproof.smaverk.com/r/%40j0hanz/filesystem-mcp)
New version out? Ask for a fresh report.