Filesystem MCP

Filesystem MCP

Let your AI assistant work with your files, safely.

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

What is this?

Model Context Protocol (MCP) 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 .gitignored files and folders like node_modules. Edits are exact-match replacements that fail loudly instead of guessing, and you can preview them as a diff first.
• It goes easy on 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 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, checked against its README on 2026-10-11:

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.

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

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

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

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

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

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

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

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/project:/workspace:ro",
        "ghcr.io/j0hanz/filesystem-mcp:latest",
        "--read-only",
        "/workspace"
      ]
    }
  }
}

npm install -g @j0hanz/filesystem-mcp

Tools

✎ changes files. --read-only removes these tools.

Search and listing tools skip hidden files, .gitignored files, and folders like node_modules, dist, and .git unless the AI asks for them.

Configuration

Most people only need the folder argument. These options cover the common cases:

Flags go in args after the package name, for example ["-y", "@j0hanz/filesystem-mcp@latest", "--read-only", "/path/to/project"].

The full configuration reference covers every flag and environment variable, the complete secret-file list, limits, HTTP setup with API keys, Docker, and troubleshooting.

Security

If you find a vulnerability, please report it privately. SECURITY.md explains how.

Build your own client

You can also call Filesystem MCP from your own code: an agent, an editor plugin, a web app, a CI job, or a script. The same rules apply as for an AI app, so your code cannot reach outside the allowed folders or read secret files.

import { Client } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';

const dir = '/path/to/project';
const client = new Client(
  { name: 'my-app', version: '1.0.0' },
  { capabilities: { elicitation: { form: {} } }, versionNegotiation: { mode: 'auto' } },
);
client.setRequestHandler('elicitation/create', async () => ({ action: 'decline' }));
await client.connect(
  new StdioClientTransport({
    command: 'npx',
    args: ['-y', '@j0hanz/filesystem-mcp', dir],
    cwd: dir,
  }),
);

const result = await client.callTool({ name: 'search_text', arguments: { searchPattern: 'TODO' } });
const { matches } = (result.structuredContent ?? result._meta) as { matches: unknown[] };
console.log(matches);
await client.close(); // stops the server process; without it the script never exits

The basics:

• Where the data is. The text block is written for a model. The same data as JSON is in _meta for tools that write their own text (list, search_text, edit, ...) and in structuredContent for stat, create, and list_roots. read is the exception: the file's text is only in the text block, and _meta holds metadata about it.
• Paths. Relative paths resolve against the server's working directory, not its root: set cwd over stdio, and send absolute paths over HTTP.
• Confirmations. Overwrites, recursive deletes, and paths outside the roots are questions for the user. Declare the elicitation capability and answer them in a handler, or, on the 2026-07-28 protocol, take them as data (input_required) and answer later.
• Protocol versions. The server speaks the 2025 protocol and 2026-07-28, over stdio and Streamable HTTP. Over HTTP, 2025-era clients get no confirmations or change notifications.
• Resources. Read and subscribe to any file as filesystem-mcp://file/{+path}; internal://instructions and the get-help prompt hold the server's guide for models.

The client guide has the details, tested with the TypeScript and Python SDKs, and examples/ has six runnable clients:

Privacy Policy

Filesystem MCP runs entirely on your machine. This policy covers the npm package, the Docker image, and the .mcpb desktop extension.

• Data collection: none. The server has no telemetry, analytics, or crash reporting, and makes no outbound network requests.
• Use and storage: files are read and written only inside the folders you allow, and only when your MCP client calls a tool. Tool results go to that client and nowhere else. Short-lived result caches live in memory and disappear when the server exits.
• Third-party sharing: none by this server. Your MCP client may send tool results to its model provider under that client's own privacy policy.
• Retention: nothing is kept after the process exits. Diagnostic logs go to stderr on your machine; your MCP client may save them in its own log files.
• Contact: open an issue at https://github.com/j0hanz/filesystem-mcp/issues, or report security problems privately through GitHub Security Advisories.

Contributing

Bug reports, ideas, and pull requests are welcome. Start with CONTRIBUTING.md: it covers setup, running the server from source, and the checks a pull request needs.

If Filesystem MCP is useful to you, a star on GitHub helps other people find it.

License

MIT