Filesystem MCP Server: Tools, Allowed Directories and Setup

The filesystem MCP server is the reference server that lets an AI assistant read, write, edit, move and search files on your computer, but only inside the folders you name. It's a small Node.js program from the official modelcontextprotocol/servers repository, published on npm as @modelcontextprotocol/server-filesystem.

Here's the short version:

• What it gives the AI: 13 documented tools for reading files, writing and editing them, creating folders, moving things around, and searching.
• What limits it: an allow-list of directories. You pass them on the command line, and every operation outside them is refused.
• How to run it: add a few lines to claude_desktop_config.json, using either npx (needs Node.js 24 or later) or Docker.
• The read-only option: the README documents one, the Docker ro mount flag. There is no read-only command-line switch.

Below: the full tool list, how the allowed-directories model works (including what changed with MCP Roots), the exact configs from the README, and what to think about before you point it at your files.

What the filesystem MCP server does

MCP (Model Context Protocol) is the open standard that lets AI apps call outside tools. If the term is new, our plain-English MCP explainer covers the basics in a few minutes.

On its own, a chat assistant can only see what you paste or upload. Once the filesystem MCP server is connected, you can say "What work-related files are in my downloads folder?" or "Please organize all images on my desktop into a new folder called 'Images'" and the assistant does the file work itself. Those two examples come straight from the official Connect to local MCP servers guide, which uses this exact server as its walkthrough.

Two things set it apart from the dozens of community "mcp filesystem" projects you'll find on GitHub and in directories:

• It lives in the official repo. The servers repository now keeps only a small set of reference servers maintained by the MCP steering group, and Filesystem is one of them.
• It's a reference implementation, not a product. The repo says its servers are "educational examples" and "not production-ready solutions," and tells developers to evaluate their own security requirements. Keep that in mind for the security section below.

The filesystem MCP server tool list

The filesystem server README documents 13 tools. Here they are, grouped by whether they can change anything:

A few details worth knowing:

• There is no delete tool. The README's feature summary mentions deleting directories, but none of the 13 documented tools deletes anything. The closest thing is write_file overwriting a file, or move_file relocating one.
• edit_file has a preview mode. Set dryRun: true and you get a git-style diff without any change applied. The README's own advice is to always dry-run first.
• write_file is not crash-safe. The README notes the overwrite "is not crash-atomic," so a crash mid-write can leave a file partly written. It also refuses to replace a read-only file.
• Older guides mention read_file. The source still registers it, but marks it deprecated in favour of read_text_file.

The server also labels every tool with MCP tool annotations: the nine read tools carry readOnlyHint: true, and write_file, edit_file and move_file are flagged as destructive. A client can use those hints to decide which calls deserve a confirmation prompt. They are hints, though. The MCP tools spec says clients "MUST consider tool annotations to be untrusted unless they come from trusted servers."

How allowed directories work, and what changed with MCP Roots

The whole security model rests on one idea: the server can only touch its allowed directories. Every tool call is checked against that list, and list_allowed_directories shows you what's on it.

Command-line arguments (the method to use)

You pass the allowed directories when the server starts:

mcp-server-filesystem /path/to/dir1 /path/to/dir2

In a Claude Desktop config, those are simply the paths at the end of the args array. The README calls this "the only method that works on every protocol version, so it is the one to use."

MCP Roots (deprecated, older clients only)

Roots is an MCP feature where the client tells the server which folders it's working in. Older guides describe it as the "dynamic" way to set the filesystem server's access. That has changed:

• Roots is deprecated. MCP's deprecated features registry lists it as deprecated in protocol version 2026-07-28, with the migration path "Pass directories or files via tool parameters, resource URIs, or server configuration." Earliest removal is the first spec revision released on or after 2027-07-28.
• It only works with 2025-era clients. A client that connects the old way (the initialize handshake) and supports Roots can still send a list of folders. When it does, those roots completely replace the command-line directories, and the client can update them at runtime.
• 2026-07-28 clients never send roots. The newer protocol has no handshake and no roots request, so for those clients the command-line directories are the entire allow-list.

The edge cases matter if you're debugging a server that won't start:

The practical rule is simple: always list your directories in the config. Don't rely on your client to supply them.

Filesystem MCP server setup for Claude Desktop

In Claude Desktop, open the Claude menu in your system menu bar, choose Settings, go to the Developer tab and click Edit Config. That opens claude_desktop_config.json, which the MCP guide places at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows.

Both configs below are copied from the server's README. Replace the example paths with absolute paths to the folders you want to share.

Option 1: npx

This runs the npm package directly. The README requires Node.js 24 or later for npx or source installs.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

On Windows, the README launches npx through cmd /c:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

Option 2: Docker

Docker keeps the server inside a container. Every folder you share has to be mounted under /projects, and the final /projects argument tells the server that's its allowed directory.

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

Making a folder read-only

Look at the second --mount line above: it ends in ,ro. Per the README, "adding the ro flag will make the directory readonly by the server." That's the only read-only option the README documents. The npx setup has no read-only switch, so anything you list there is readable and writable.

A sensible pattern: mount your reference material with ro, and give write access only to one scratch folder.

Check that it worked

Fully quit and reopen Claude Desktop. In a new chat, open the "Add files, connectors, and more" menu at the bottom-left of the message box, go to Connectors → Manage connectors, and select filesystem to see its tools.

If it doesn't show up, the MCP guide's troubleshooting list is short: check the JSON syntax, make sure every path is absolute, and read the logs in ~/Library/Logs/Claude (macOS) or %APPDATA%\Claude\logs (Windows). Files named mcp-server-filesystem.log hold the server's own output. You can also run the same npx command in a terminal to see the error directly.

Using Claude Code rather than Claude Desktop? The server and its arguments are the same; only the place you register it changes. Our Claude Code MCP configuration guide covers scopes and the .mcp.json file.

Filesystem MCP server security: what to check first

Giving an AI write access to your disk is a real decision. The MCP guide's own warning is blunt: "The server runs with your user account permissions, so it can perform any file operations you can perform manually." Inside the allowed directories, that's exactly what it can do.

What keeps it in check:

• The allow-list. Nothing outside your listed folders is reachable. Pick narrow folders, not your whole home directory.
• Client approval prompts. The MCP spec says there "SHOULD always be a human in the loop with the ability to deny tool invocations," and the Claude Desktop guide says Claude asks for your approval before each file operation. Read the request before you click allow, especially for write_file, edit_file and move_file.
• Read-only mounts. With Docker, ro turns a folder into look-but-don't-touch.

What it doesn't protect you from:

• Prompt injection through file contents. If the assistant reads a file containing hidden instructions, those words land in its context like anything else. Combine a filesystem server with a web or email server and a malicious document can try to steer one tool into misusing another. We cover this pattern, and a pre-connection checklist, in MCP security risks.
• Overwrites. write_file replaces content in place, and there's no delete tool to undo with. Keep important folders under version control or backed up before you share them.
• Look-alike packages. Many unofficial filesystem servers exist with similar names. Install the exact package name from the official README.

Is the filesystem MCP server right for you?

It's the right tool if you want an assistant to work with local documents, notes or code in a few specific folders, and you're comfortable editing a JSON config file. It's also the best first MCP server to learn on, since it's the one the official docs teach with. If you want more ideas once it's running, our roundup of the best MCP servers is a good next stop.

Key points to take away:

• The filesystem MCP server exposes 13 file tools, nine of them read-only, and no delete tool.
• Access is limited to allowed directories. List them on the command line; Roots is deprecated as of protocol 2026-07-28.
• Claude Desktop setup is one JSON block, via npx (Node.js 24+) or Docker.
• Docker's ro mount flag is the only documented read-only option.
• It's a reference implementation. Narrow folders, approval prompts and backups are on you.

If wiring up configs and folder mounts is where you keep getting stuck, Taku mirrors a working AI setup into a desktop workspace and runs it, so you can start from a configuration someone already got working. Taku is in Beta, and the Mac app is available now.

FAQ

What is the filesystem MCP server?

It's an official reference MCP server, written in Node.js, that gives an AI client tools to read, write, edit, move and search files. It only works inside directories you explicitly allow.

Is the MCP filesystem server safe to use?

It's as safe as the folders you give it. It runs with your user permissions inside those folders, and the repo calls its servers educational examples rather than production-ready software. Share narrow folders, use read-only mounts where you can, and review each approval prompt.

Can the filesystem MCP server delete files?

None of its 13 documented tools deletes files or folders. It can overwrite a file with write_file and move one with move_file, so it can still change or relocate your data.

How do I make the filesystem MCP server read-only?

The README's documented option is Docker: add ,ro to the end of a --mount line and the server can only read that folder. The npx setup has no read-only flag.

Does the filesystem MCP server still support MCP Roots?

Only for clients on a 2025-era protocol version, where roots sent by the client replace the command-line directories. Roots is deprecated as of protocol version 2026-07-28, and newer clients never send them, so list your directories in the config.

What Node.js version does the filesystem MCP server need?

The README says Node.js 24 or later when you run it through npx or from source. The README states that requirement only for those two methods, not for the Docker setup.

Where is the Claude Desktop config file?

On macOS it's ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows it's %APPDATA%\Claude\claude_desktop_config.json. You can open it from Settings → Developer → Edit Config.