# Filesystem MCP

Local file operations server with directory restrictions, secret shielding, and diff previews. Keeps sensitive credentials and unapproved edits safe.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 26
- Author: j0hanz
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/j0hanz/filesystem-mcp
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/filesystem-mcp

## What it does

This server gives the assistant 14 tools to inspect, query, and modify code. Operations stay locked to selected folders, keeping the rest of the disk off limits. The server automatically hides `.env` files, private keys, and cloud tokens. Overwriting existing files via `create` or deleting populated folders pauses for user confirmation.

File searching uses an RE2 regular expression engine that avoids catastrophic backtracking. Listing and search actions honor `.gitignore` entries and bypass paths like `node_modules`. Text replacements execute on exact matches, with an optional `dryRun` diff check. If editing must be completely prevented, the `--read-only` flag strips all modifying tools.

Running this server requires Node.js 24 or newer. Communication works over standard input-output or streamable HTTP, with zero telemetry and no outbound network calls.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `FS_ALLOWED_DIRS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env FS_ALLOWED_DIRS=<FS_ALLOWED_DIRS> --transport stdio filesystem-mcp -- npx -y @j0hanz/filesystem-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add filesystem-mcp --env FS_ALLOWED_DIRS=<FS_ALLOWED_DIRS> -- npx -y @j0hanz/filesystem-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "filesystem-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@j0hanz/filesystem-mcp"
            ],
            "env": {
                "FS_ALLOWED_DIRS": "<FS_ALLOWED_DIRS>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "filesystem-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@j0hanz/filesystem-mcp"
            ],
            "env": {
                "FS_ALLOWED_DIRS": "<FS_ALLOWED_DIRS>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e FS_ALLOWED_DIRS=<FS_ALLOWED_DIRS> filesystem-mcp npx -y @j0hanz/filesystem-mcp
```
Replace <…> with your own values

## When to use it
- restrict assistant access to specific project folders
- hide environment files and private encryption keys
- search codebases using RE2 regular expressions
- apply unified diff patches directly
- inspect line-by-line differences between two files

## Example prompts
- Find all TODO comments across the project and group them by file.
- Replace getUser with fetchUser in all .ts files, but show the diff first.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md