# Filesystem MCP

> Filesystem MCP is a free MCP server for files and documents. Local MCP server for reading, searching, editing and patching files in chosen folders. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** macOS, Windows, Linux, CLI
- **Repository:** https://github.com/j0hanz/filesystem-mcp
- **MCP Registry name:** io.github.j0hanz/filesystem-mcp
- **Categories:** [files and documents](https://ai-powered.com/categories/files-and-documents), [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

Safety is the main design idea. The assistant can only touch the folders you list, secret files such as .env files, private keys and cloud credentials are blocked, and it asks before deleting a non-empty folder or overwriting a file. Those questions need a client that can show them; otherwise the server refuses the action. A --read-only flag strips every tool that writes, and a per-folder read-only option guards chosen directories.

The README compares it with the official reference filesystem server: it adds in-file search through search_text (literal or RE2 regex), a unified-diff patch tool, diff between two files, replace_text across a folder or glob, file watching, and an undo that skips files you edited afterwards. Edits are exact-match, and a dryRun option shows the diff first.

It runs on your machine with no telemetry and no network calls, over stdio or Streamable HTTP, and needs Node.js 24 or later. Install through npx, Docker or a Claude Desktop extension.

## Features

- **Folder allow-list:** Only directories you configure are reachable; everything else is off limits.
- **Secret blocking:** Blocks .env files, private keys and cloud credentials by default.
- **Search inside files:** search_text matches literal text or RE2 regex and skips gitignored paths.
- **Previewable edits:** edit, patch and replace_text can show a diff with dryRun before writing.
- **Undo:** Reverts recent changes but leaves files you edited afterwards alone.
- **Read-only modes:** A global flag or per-folder guard removes or refuses write tools.

## Good for

- Find every TODO in a repository and group them by file
- Rename a function across all TypeScript files after reviewing the diff
- Compare two config files
- Read the tail of a large log file and explain an error
- Move old screenshots into an archive folder

## Install

### Claude Code (Terminal)

```sh
claude mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "filesystem-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@j0hanz/filesystem-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `search_text`: Searches inside files with literal text or RE2 regex.
- `create`: Creates a file and asks before overwriting one.
- `move`: Moves files and asks before overwriting.
- `delete`: Deletes files and asks before removing a non-empty folder.
- `undo`: Reverts recent changes, skipping files edited since.
- `edit`: Applies exact-match replacements.
- `patch`: Applies a unified diff.
- `replace_text`: Replaces text across a folder or glob.
- `diff`: Compares two files.

## FAQ

### Does it send data over the network?

No. The README says it makes no network calls and has no telemetry.

### What Node.js version is needed?

Node.js 24 or later.

### Can it overwrite files without asking?

Not by default. create and move ask first, though overwrite: true on create replaces a file without a prompt.

### How many tools does it expose?

The README says 14.

### Is Filesystem MCP free?

Yes. Filesystem MCP is free to use.

### How do I add Filesystem MCP to Claude Code?

Run this command in your terminal: claude mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp

### What are the best alternatives to Filesystem MCP?

The closest alternatives to Filesystem MCP are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/filesystem-mcp
