Log inSubmit server
Filesystem MCP logo

Filesystem MCP

Read, search, compare, edit, and manage files within explicitly allowed local directories over MCP.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Filesystem MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@j0hanz/filesystem-mcp@latest"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y @j0hanz/filesystem-mcp@latest

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 8d ago.

Overview

Filesystem MCP MCP server lets MCP-compatible AI clients inspect and modify files inside explicitly permitted local directories. It provides tools for directory listing, glob-based discovery, metadata inspection, text search, reading, creation, editing, moving, copying, deletion, replacement, and patching. The server validates paths against allowed roots, blocks sensitive patterns such as `.env`, `*.pem`, and `*id_rsa*` by default, and supports stdio or Streamable HTTP transport. Reach for it when an agent needs controlled access to a local project, especially for code navigation, file updates, or review workflows.

Use cases

  • Browse a project directory and inspect its files
  • Search source files for text or glob patterns
  • Read selected lines from multiple files
  • Apply controlled edits or unified patches
  • Compare files and review resulting changes

Key features

  • Allowed-root path validation
  • Sensitive filename blocking
  • File discovery and content search
  • Batch reads and file operations
  • Unified diff and patch support
  • stdio and Streamable HTTP transport

Tools7

What Filesystem MCP lets your agent do. Expand a tool for its parameters.

Self-reported~126 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

4/4 checks healthy over the last 41d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 14d ago via OSV.dev · @j0hanz/filesystem-mcp@latest (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars25Stargazers on the source repository.
npm downloads5kPackage downloads in the last 30 days.
Last commit7d agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.
Tools exposed7Callable tools this server registers over MCP.
Directory activity6 viewsConfig copies, upvotes, and views on AllMCPs.

How Filesystem MCP works

What Filesystem MCP does

Filesystem MCP MCP server exposes local filesystem operations to an MCP-compatible AI client. Access is limited to directories supplied when the process starts, rather than granting the client unrestricted access to the host filesystem. The server can work across multiple allowed roots and provides a list_roots tool that should be called before other operations.

The available operations cover both inspection and modification. An agent can browse directories, locate files by glob, inspect metadata, search text, read selected portions of files, compare two files, and retrieve unified diffs. It can also create files, apply literal replacements, move or copy paths, delete files or directories, perform glob-based replacements, and apply a unified patch to one file.

How it works

Filesystem MCP MCP server accepts paths only when they resolve within an allowed workspace root. Sensitive filename patterns are denied by default, including .env, *.pem, and names containing id_rsa. This provides a path and filename boundary around the directories exposed to the client.

The default connection uses stdio. Starting the process with --port enables Streamable HTTP, including support for the transport versions described by the project. The implementation uses Node.js and requires version 24 or newer. Regex-based search uses RE2, which provides linear-time matching and does not support lookahead, lookbehind, or backreferences.

Most operations can process multiple paths or files in one request. The read tool supports batches as well as head, tail, and line-range selection. Directory listings return directories first, followed by alphabetical entries, together with an ASCII tree. File metadata includes size, modification time, permissions, MIME type, and an estimated token count.

Setup and configuration

Filesystem MCP MCP server can be run directly with npx:

Terminal
npx -y @j0hanz/filesystem-mcp /path/to/allowed/dir

It can also be installed globally with npm and started as filesystem-mcp /path/to/allowed/dir. Node.js 24 or later is required. Docker is optional; the documented container example mounts a project at /workspace and starts the server in read-only mode.

For VS Code, Visual Studio, Claude Desktop, and Cursor, configuration consists of an MCP server entry that runs npx -y @j0hanz/filesystem-mcp followed by one or more allowed directory paths. Claude Desktop also has a downloadable .mcpb package that prompts for directories during setup. Project-specific configuration locations are documented for VS Code and Cursor, while Claude Desktop uses its MCP server configuration file.

The --read-only option removes mutating tools. Use it when an agent should inspect or search project files without being able to create, edit, move, copy, replace, patch, or delete them.

Tools and capabilities

  • list_roots reports the directories available to the session.
  • list, find_files, stat, and search_text support navigation, discovery, metadata inspection, and content search.
  • read retrieves complete files or selected ranges and accepts batches.
  • diff compares two files and reports a unified diff with added and removed line counts.
  • create, edit, move, delete, replace_text, and patch provide file mutation workflows.
  • move can rename or copy paths when copy: true is used.
  • File resource subscriptions can send change notifications when watched files are updated.

Deletion is permanent. Literal replacement through edit is sequential and supports up to five files per call, while replace_text applies a bulk replacement to files selected by a glob pattern.

Limitations and notes

The server does not provide unrestricted filesystem access: every path must remain under an allowed root, and protected filename patterns are blocked by default. The patch operation applies a single-file unified diff, while diff compares two files without applying changes. RE2 search patterns cannot use lookahead, lookbehind, or backreferences.

The project lists Node.js 24 or later as a prerequisite. HTTP use requires starting the server with --port; otherwise, clients connect through stdio. Because mutation tools can overwrite, move, or permanently delete data, use an allowed workspace with appropriate backups and choose --read-only for analysis-only tasks.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Filesystem MCP

Filesystem MCP is an MCP server that connects AI clients to explicitly allowed local directories. Its main tools list roots, browse directories, find files, inspect metadata, search text, read files, create and edit content, move or copy paths, delete items, replace text, compare files, and apply patches. It supports controlled filesystem access over stdio or Streamable HTTP.

Install it with `npx -y @j0hanz/filesystem-mcp /path/to/allowed/dir` and provide Node.js 24 or newer. You can also install the npm package globally, run it in Docker, or add the same command and allowed path to an MCP configuration for a supported client.

Yes, Filesystem MCP works with Cursor through `.cursor/mcp.json`. Add an `mcpServers` entry that runs `npx -y @j0hanz/filesystem-mcp@latest` and passes the project directory or another allowed path. The configuration can be project-scoped or placed in Cursor's global MCP configuration.

Start the server with the `--read-only` option. This removes every mutating tool, leaving the client with filesystem inspection and reading capabilities. The Docker example also mounts the workspace read-only, providing a matching container-level restriction.

Filesystem MCP blocks sensitive patterns including `.env`, `*.pem`, and `*id_rsa*` by default. It also validates every requested path against the explicitly allowed workspace roots, so a client cannot use the server to access paths outside those roots.

Related MCP servers

All in File Systems All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewFilesystem MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/filesystem-mcp?style=directory)](https://allmcps.com/mcp/filesystem-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/filesystem-mcp"><img src="https://allmcps.com/api/badge/filesystem-mcp?style=directory" alt="Filesystem MCP on AllMCPs" /></a>