filesystem-mcp

<img src="assets/logo.png" alt="Filesystem MCP logo" width="96" height="96">

# Filesystem MCP

**Let your AI assistant work with your files, safely.**

Read, search, edit, and patch files in the folders you choose.<br>
Secret files stay hidden, and risky changes wait for your OK.

[![npm version](https://img.shields.io/npm/v/%40j0hanz%2Ffilesystem-mcp?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@j0hanz/filesystem-mcp) [![CI](https://img.shields.io/github/actions/workflow/status/j0hanz/filesystem-mcp/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=CI)](https://github.com/j0hanz/filesystem-mcp/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/github/license/j0hanz/filesystem-mcp?style=flat-square)](LICENSE) [![GitHub stars](https://img.shields.io/github/stars/j0hanz/filesystem-mcp?style=flat-square&logo=github)](https://github.com/j0hanz/filesystem-mcp/stargazers)

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D&quality=insiders) [![Install in Visual Studio](https://img.shields.io/badge/Visual_Studio-Install-C16FDE?style=flat-square&logo=visualstudio&logoColor=white)](https://vs-open.link/mcp-install?%7B%22filesystem-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D%7D) [![Install in Cursor](https://img.shields.io/badge/Cursor-Install-000000?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=filesystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) [![Install in Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Install-D97757?style=flat-square&logo=claude&logoColor=white)](https://github.com/j0hanz/filesystem-mcp/releases/latest/download/filesystem-mcp.mcpb)

## What is this?

[Model Context Protocol (MCP)](https://modelcontextprotocol.io) is how AI apps
such as Claude, GitHub Copilot in VS Code, and Cursor connect to tools.
Filesystem MCP is an MCP server: a small program that runs on your computer
and gives the AI 13 tools for working with files. You choose which folders it
can use, and everything outside them is off limits.

Once it is connected, you can ask things like:

- _"Find every TODO in this repo and group them by file."_
- _"Rename `getUser` to `fetchUser` in all `.ts` files. Show me the diff first."_
- _"What changed between `config.dev.json` and `config.prod.json`?"_
- _"Read the last 50 lines of `server.log` and explain the error."_
- _"Move the old screenshots into `archive/2025/`."_

## Why Filesystem MCP?

- It is safe by default. The AI can use only the folders you allow, and
  `.env` files, private keys, and cloud credentials are blocked. The server
  asks you before the AI deletes a non-empty folder, opens a folder you did
  not allow, or writes over a file with `create` or `move`. Only `create` and
  copies can skip that question, by passing `overwrite: true`. Edits made with
  `edit`, `patch`, and `replace_text` apply without asking, but the AI can
  show you the diff first with `dryRun`. If the AI should never change
  anything, `--read-only` removes every tool that writes.
- Search and editing are made for code. The AI can search inside files like
  `grep`, with a regex engine (RE2) that cannot hang, and by default the
  server skips `.gitignore`d files and folders like `node_modules`. Edits are
  exact-match replacements that return an error when the text does not match,
  and you can preview them as a diff first.
- It saves the AI's context. The AI can read many files in one call or
  only the lines it needs, and it can check a file's size and token estimate
  before reading it.
- It works with any MCP client, over stdio or HTTP, on macOS, Linux, and
  Windows. You can install it with npx, Docker, or a one-click Claude Desktop
  extension, or [build your own client](#build-your-own-client) on it.
- It is private. It runs on your machine, has no telemetry, and makes no
  network calls.

### Compared with the reference server

How this server differs from the official
[`@modelcontextprotocol/server-filesystem`](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem),
checked against its README on 2026-10-11:

| Capability                | Filesystem MCP                                     | Reference server                        |
| :------------------------ | :------------------------------------------------- | :-------------------------------------- |
| Search inside files       | `search_text`: literal text or RE2 regex           | None; `search_files` matches names only |
| Secret files              | `.env`, keys, and credentials blocked by default   | Not blocked                             |
| Overwriting a file        | `create` asks you first (unless `overwrite: true`) | `write_file` overwrites without asking  |
| Delete files              | `delete`; asks before deleting a non-empty folder  | None                                    |
| `.gitignore`              | Respected by listing and search tools              | Not supported                           |
| Read-only mode            | `--read-only` removes every tool that writes       | Docker `ro` mounts only                 |
| Apply a unified diff      | `patch`                                            | None                                    |
| Compare two files         | `diff`                                             | None                                    |
| Replace across many files | `replace_text` over a folder or glob               | None                                    |
| Watch files               | Subscribe to a file and get change notifications   | None                                    |
| Transport                 | stdio, or Streamable HTTP with `--port`            | stdio                                   |

## Quick start

> [!NOTE]
> You need Node.js 24 or later. Check with `node --version`.

1. Add the server to your AI app. Pick yours below.
2. Replace `/path/to/project` with the folder the AI may use. You can list
   several folders.
3. Restart the app and ask: _"Which folders can you access?"_

> [!TIP]
> VS Code currently shares the folders you have open with the server, so the
> one-click VS Code install works without a path. In other apps, or over HTTP,
> put the folder in `args`. If the AI says it has no folders, that is the fix.

<details>
<summary><b>VS Code</b></summary>

Click **Install in VS Code** above, or add this to `.vscode/mcp.json`:

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

Or from a terminal:

```sh
code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","/path/to/project"]}'
```

</details>

<details>
<summary><b>Cursor</b></summary>

Click **Install in Cursor** above, then add your folder to `args`. Or add this
to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for all
projects:

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

</details>

<details>
<summary><b>Claude Desktop</b></summary>

For a one-click install, download
[`filesystem-mcp.mcpb`](https://github.com/j0hanz/filesystem-mcp/releases/latest/download/filesystem-mcp.mcpb),
open it with Claude Desktop, and pick the folders to allow. Claude Desktop's
built-in Node.js runs it.

To set it up by hand, add this to `claude_desktop_config.json`
(Settings → Developer → Edit Config):

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

</details>

<details>
<summary><b>Claude Code</b></summary>

```sh
claude mcp add filesystem -- npx -y @j0hanz/filesystem-mcp@latest /path/to/project
```

Or install the plugin, which points the server at your current project:

```text
/plugin marketplace add j0hanz/j0hanz-marketplace
/plugin install filesystem-mcp@j0hanz-marketplace
```

</details>

<details>
<summary><b>Visual Studio</b></summary>

Add this to `.vs\mcp.json` in your solution folder, or `%USERPROFILE%\.mcp.json`
for all solutions:

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

</details>

<details>
<summary><b>GitHub Copilot CLI and Antigravity CLI (plugin)</b></summary>

The [filesystem-mcp plugin](https://github.com/j0hanz/j0hanz-marketplace/tree/main/plugins/filesystem-mcp)
sets the server up for your current project:

| Client          | Install                                                                                                                         |
| :-------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| Copilot CLI     | `copilot plugin marketplace add j0hanz/j0hanz-marketplace`, then `copilot plugin install filesystem-mcp@j0hanz-marketplace`     |
| Antigravity CLI | `git clone https://github.com/j0hanz/j0hanz-marketplace`, then `agy plugin install ./j0hanz-marketplace/plugins/filesystem-mcp` |

</details>

<details>
<summary><b>Docker</b></summary>

The container can only see