All servers / Files / Filesystem (J0hanz)
Filesystem (J0hanz)
Search, read and edit local files.
Tested by ConnectATDScore 90 out of 100. Tested 2026-11-17 on package version 2.23.0. Package: @j0hanz/filesystem-mcp · source
Score breakdown
| Runs | 18 / 20 | |
|---|---|---|
| Tool descriptions | 20 / 20 | |
| Package safety | 20 / 20 | |
| Maintenance | 20 / 20 | |
| Adoption | 12 / 20 |
What we saw
- Starts and answers the MCP handshake: yes (13.9 seconds including download)
- Tools offered: 14
- Last published: 2026-11-17
- Weekly downloads (npm): 1,450
- License: MIT · Direct dependencies: 8
Want this server set up for your team?
ConnectATD builds AI automation and wires up MCP servers like this one. Tell us what you are trying to do.
Talk to ConnectATDTools and how they are described
Agents choose tools from these descriptions. Under each name you can see how many of its parameters are explained.
create2 of 2 parameters describedWrite 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.
delete3 of 3 parameters describedDelete 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.
diff3 of 3 parameters describedCompare 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.
edit6 of 6 parameters describedReplace 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.
list9 of 9 parameters describedList 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).
move3 of 3 parameters describedMove, 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.
patch3 of 3 parameters describedApply 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.
read9 of 9 parameters describedRead 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. Non-UTF-8 text is returned with U+FFFD and lossy: true. 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_text15 of 15 parameters describedReplace 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_rootsno parametersList 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_text12 of 12 parameters describedSearch 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_files10 of 10 parameters describedFind 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.
stat2 of 2 parameters describedGet 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.
undo3 of 3 parameters describedRevert 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.
Tested in a sandbox with an empty environment: no API keys, a throwaway folder, nothing from a real account. A passing test shows the server runs and responds. It is not a security audit.