# Filesystem MCP [Health: Active]

**Category:** 📂 File Systems  
**Repository:** https://github.com/j0hanz/filesystem-mcp  
**GitHub Stars:** 25  
**npm Downloads (last month):** 5009  
**Views:** 6  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/filesystem-mcp

## Description
MCP Server that enables LLMs to interact with the local filesystem.

## Tools
Capabilities this server exposes over MCP:

- **list_roots** — Shows the folders the server may use.
- **list** — Lists a folder as a tree, like `ls` or `tree`.
- **find_files** — Finds files by name or glob, such as `**/*.test.ts`.
- **search_text** — Searches inside files for text or a regex, like `grep`, with optional context lines.
- **stat** — Gets size, dates, type, permissions, and a token estimate without reading the file.
- **read** — Reads text files whole or by lines, head, or tail. Images and audio come back as media; others with `binary`.
- **diff** — Compares two files and returns a unified diff.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "filesystem-mcp": {
    "command": "npx",
    "args": ["-y","@j0hanz/filesystem-mcp@latest"]
  }
}
```

## Documentation

## 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`:

```bash
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.

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