Filesystem MCP Server

Name: Filesystem MCP Server
Author: j0hanz

@j0hanz

Repository Documentation

Basic information

About Filesystem MCP Server

Read-only MCP server for secure filesystem exploration, searching, and analysis

#filesystem #mcp #search #security #diff#patch#file-management #regex #stdio #streamable-http#undo

Filesystem MCP Server config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@j0hanz/filesystem-mcp@latest",
        "/path/to/project"
      ]
    }
  }
}

Filesystem MCP Server tools

Write whole text files: create new ones, overwrite, or append. Missing parent directories are created. edit or patch changes part of an existing file.

Permanently delete files, directories, or symlinks, like rm or rm -r. Paths are exact; globs are not expanded.

Compare two text files and return a unified diff from a to b, like diff -u.

Edit text files in place by replacing exact oldText with newText, like str_replace. Each oldText must match exactly once, and a file is written only if all its edits match. replace_text replaces every occurrence across files.

List a directory's files and subdirectories as a tree of names, like ls or tree. stat returns sizes and dates.

Move, rename, or copy files and directories, like mv or cp -r. Each destination is the full new path, not a folder to move into; missing parent directories are created.

Apply a single-file unified diff to one existing text file, like git apply. Nothing is written unless every hunk applies in file order with exactly matching context; hunks are found by their context, so start line numbers may be off.

Read text files, like cat: whole, or one slice via head, tail, or startLine/endLine. Images and audio return as media; other binary files are rejected.

Find and replace every occurrence of literal text or an RE2 regex, like sed -i, in one file or all files under a directory, optionally filtered by glob. The pattern runs over the whole file: it can span lines, and ^ and $ anchor to file start and end. edit replaces one unique exact match.

List the directories this server can access, as absolute paths, including any the user granted during this session. Other tools can ask the user to grant access to a path outside them.

Search file contents for literal text or an RE2 regex, like grep; returns matching lines with line numbers and paths relative to the searched directory. Patterns match within one line. find_files matches file names.

Find files by name or glob pattern; returns file paths relative to the searched directory. A pattern without / matches file names at any depth. search_text searches contents.

Get metadata without reading contents, like ls -ld: type, size (a directory reports its own entry, not its contents), tokenEstimate, timestamps, permissions, MIME type guessed from the extension, and symlink target. Also checks whether paths exist.

Overview

What is it?

Filesystem MCP is an MCP server that runs on your computer and gives an AI assistant 14 tools for working with files. You choose which folders it can use. Everything outside them is off limits, and .env files, private keys, and cloud credentials are blocked by default.

How to use it?

You need Node.js 24 or later. Add this to your MCP client and replace the path with the folder the AI may use:

npx -y @j0hanz/filesystem-mcp@latest /path/to/project

You can list several folders, or pass --allow-cwd to use the current directory. --read-only removes every tool that writes. --port 3000 serves Streamable HTTP instead of stdio. A Docker image is published at ghcr.io/j0hanz/filesystem-mcp, and Claude Desktop has a one-click .mcpb extension.

Key features

The AI can use only the folders you allow. Secret files stay blocked unless you exempt them.
The server asks you before the AI deletes a non-empty folder, opens a folder you did not allow, or overwrites a file with create or move. If your client cannot show the question, the server refuses.
undo reverts recent changes and skips any file you have edited since.
search_text searches inside files with literal text or RE2 regex, which cannot hang. Listing and search skip .gitignored files.
edit makes exact-match replacements and fails when the text does not match. replace_text does the same across a folder or glob. Both can show a diff first with dryRun.
diff compares two files and patch applies a unified diff. A patch that no longer fits changes nothing.
The AI can read many files in one call, read only the lines it needs, and check a file's size and token estimate first.
--read-only-root protects chosen folders inside a writable one.
It runs locally, has no telemetry, and makes no network calls.

Use cases

Give a coding agent access to one project without exposing the rest of your disk.
Rename a symbol across a repo and review the change as one diff before it is written.
Find an error in a large log by reading only its tail.
Tidy files into an archive and undo the move if it went wrong.

FAQ

Can it write files? Yes. create, edit, move, delete, replace_text, and patch write inside allowed folders. Start with --read-only to remove them, along with undo.

How do I allow folders? Pass them as arguments, set FS_ALLOWED_DIRS, use --allow-cwd, or let the MCP client supply roots. --root-boundary limits which roots can be added.

Which files are blocked? .env files, keys, and credentials. Add patterns with --deny, or exempt one with --allow.

What transport does it use? stdio by default. --port <number> starts Streamable HTTP. Set FS_API_KEY to require a key on every request.

What does it need? Node.js 24 or later. Docker is optional.