j0hanz/filesystem-context-mcp-server

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.

npm version CI License: MIT GitHub stars HOL Trust Filesystem MCP security badge Filesystem MCP status badge

Install in VS Code Install in VS Code Insiders Install in Visual Studio Install in Cursor Install in Claude Desktop

filesystem-mcp MCP server – quality and maintenance score on Glama

Real sessions with a real model, except the web client demo. The apply? prompt comes from the example gatekeeper client, not the server.

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 14 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. These questions need a client that can show them. If yours cannot, the server refuses each of those actions instead of asking. Only create and copies can skip the question, because overwrite: true replaces a file without asking, on any client. undo can usually restore a file create replaced, but a copy cannot be undone. 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 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 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-11-05:

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. To refuse changes under one folder while the rest stay writable, pass --read-only-root <dir> (repeatable, or FS_READ_ONLY_DIRS): those tools still exist, but a call that writes, moves, or deletes under the folder fails with Read-only root: ..., while listing, searching, and reading keep working.

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. A relative path resolves against the server's working directory when that is inside a root, and against the root otherwise. With several roots, it must exist under exactly one of them. Absolute paths are never ambiguous. Search results are printed relative to the root, or absolute when a relative path would not read back, so a result can be passed straight back. A name that differs from the one on disk only in Unicode form (NFC or NFD) or in its space characters (U+00A0, U+202F) finds that entry.
• 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. A client that can do neither gets a refusal. overwrite: true on create and copies never asks.
• 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 starts no network connections of its own. SECURITY.md names the Windows paths that make the OS contact a host.
• Use and storage: the server reads and writes files 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 and the undo history (saved file contents) 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: the server keeps nothing 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.

Contributors

License

MIT