How to set up the Filesystem MCP server

Quick answer

• Needs: Node.js 24 or newer (since v2.0.0).
• Command: npx -y @modelcontextprotocol/server-filesystem /path/to/folder. Every folder the AI may use goes at the end, as its own argument.
• Claude Code: claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/folder
• Windows: launch it through cmd /c npx ... in JSON configs, as the README does.
• Read-only: use the Docker image with ,ro on the mount, or limit the tools in your client.

Before you start

Check your Node version with node --version. Version 2.0.0 of the server raised the minimum to Node 24, and the README lists Node 24 or later as the requirement when you run it through npx.

Then decide which folders to share. The server can only touch the folders you list and what is inside them, but within those it can create, overwrite and move files. Pick a project folder or a notes folder, not your whole home directory.

How allowed folders work

You pass allowed folders as command-line arguments after the package name. The README calls this the recommended method, and it is the only one that works with every protocol version.

There is an older method called Roots, where the client tells the server which folders to use and replaces the command-line list. It is deprecated as of the 2026-07-28 protocol version and only works with 2025-era clients. Don't rely on it. Two consequences of starting the server with no folders:

• With a 2025-era client that doesn't support Roots, the server logs the reason, closes the connection and exits with status 1.
• With a 2026-07-28 client, the server starts but answers every tool call with an error saying no directories are allowed.

To check what the server thinks it can access, ask the AI to call list_allowed_directories. A folder you reached through a symlink is listed twice, once as you typed it and once as its real path.

Set it up in your client

Claude Code

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects/my-app

# more than one folder: add them at the end
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects/my-app ~/notes

Everything after -- is the command Claude Code runs. Run claude mcp list or /mcp to check it connected. More: the best MCP servers for Claude Code.

Claude Desktop

Open Settings → Developer → Edit Config and add this to claude_desktop_config.json, with your own folder paths:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Desktop",
        "/Users/you/Documents/notes"
      ]
    }
  }
}

Quit Claude Desktop fully and reopen it. The full walkthrough, including where the file is on each OS, is in how to add an MCP server to Claude Desktop.

Windows

On Windows, the README launches npx through cmd /c. In JSON, every backslash in a path has to be doubled:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\you\\Documents\\notes"
      ]
    }
  }
}

If the client can't start npx at all, see fix spawn npx ENOENT on Windows. Version 2.1.0 fixed a bug on case-insensitive file systems (Windows NTFS, default macOS APFS) where a path that spelled the allowed folder's name in a different letter case was refused.

Cursor

Use the same mcpServers block as Claude Desktop in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). More: how to add an MCP server to Cursor.

VS Code (GitHub Copilot)

VS Code uses servers rather than mcpServers. ${workspaceFolder} gives the server whatever folder you have open:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

More: how to add an MCP server to VS Code.

Codex

codex mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/you/projects

Or edit ~/.codex/config.toml directly. Both are covered in how to add an MCP server to Codex.

Read-only and Docker setups

If you want the AI to look but not touch, there are two ways.

Docker with read-only mounts. The official image is mcp/filesystem. Each folder is mounted under /projects, and adding ,ro to a mount makes that folder read-only for the server:

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--mount", "type=bind,src=/Users/you/projects/my-app,dst=/projects/my-app",
        "--mount", "type=bind,src=/Users/you/Documents/reference,dst=/projects/reference,ro",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

Inside the container the AI sees paths like /projects/my-app/README.md, not your real paths. Docker has to be running before the client starts the server.

Only allow the read tools. If your client lets you switch off individual tools, you can leave only the read tools on. The read-only ones are read_text_file, read_media_file, read_multiple_files, list_directory, list_directory_with_sizes, directory_tree, search_files, get_file_info and list_allowed_directories. Turning off write_file, edit_file, move_file and create_directory leaves the AI able to read only. In the OpenAI Agents SDK you can do the same with a tool filter (see the Agents SDK tutorial).

What the tools do

• read_text_file: reads a file as UTF-8 text. head or tail (not both) returns only the first or last N lines. The older name read_file still works but is deprecated.
• read_media_file: returns images and audio as base64 with their MIME type. Other files come back as an embedded resource.
• read_multiple_files: reads several files at once. One failed file doesn't stop the rest.
• write_file: creates a file or overwrites an existing one completely.
• edit_file: makes targeted edits and returns a git-style diff. dryRun: true previews the change without writing it.
• create_directory: creates a folder, including parent folders. Does nothing if it already exists.
• list_directory and list_directory_with_sizes: list a folder with [FILE] and [DIR] labels. The sizes version can sort by name or size.
• move_file: moves or renames. Fails if the destination exists.
• search_files: finds files and folders by glob pattern. excludePatterns skips folders such as node_modules.
• directory_tree: returns the folder structure as JSON, also with excludePatterns.
• get_file_info: size, dates, type, permissions and hard-link count.
• list_allowed_directories: shows which folders the server may use.

The server marks its tools with MCP hints. The read tools are flagged read-only, and write_file, edit_file and move_file are flagged destructive, so clients that ask before risky actions can tell them apart.

Things worth knowing before you let it write

• Overwrites aren't crash-safe. Since 1.0.0, write_file and edit_file write into the existing file instead of swapping in a new copy. The file keeps its permissions and links, but a crash halfway through can leave it partly written. Use git or backups for anything that matters.
• Read-only files are refused rather than replaced.
• Hard links reach outside the allowed folders. The folder check looks at the path you pass, not every name a file has. pnpm, for example, hard-links package files into node_modules from a shared store, so editing one there changes it everywhere. get_file_info shows hardLinks; anything above 1 means the file has other names.
• Moving across disks works for single files since 2.1.0 (copy, then delete the original). Folders still can't be moved between disks or mounts; move the files one at a time.
• Big messages close the connection. Since 2.0.0, a single message over 10 MiB closes the stdio connection.

Slow or huge folders

Folders synced by cloud storage (macOS ~/Library/CloudStorage, iCloud Drive) or a slow network drive can stall while the provider fetches file details. Since 2.1.0 the server gives up after 15 seconds with Filesystem call timed out after 15000 ms and the path. search_files and directory_tree also stop with an error after visiting 100,000 entries, instead of returning a partial list.

For either error, ask for a narrower folder, or name the slow or large folder in excludePatterns (for example node_modules or .git). Better still, don't allow a cloud-synced folder at all if you can point the server at a local copy.

Updating from an older version

The server used date-style versions (2025.x, 2026.x) before switching to normal version numbers at 1.0.0 in October 2026. By version number, 2.1.0 is lower than any 2026.x release, so an existing install pinned to a 2026.x range won't update to it. To be sure which version you run, pin it:

npx -y @modelcontextprotocol/server-filesystem@2.1.0 /path/to/folder

What else changed in v2 across the reference servers: MCP reference servers v2: what changed.

Test it outside your client

The MCP Inspector can start the server and list its tools, which tells you whether a problem is the server or your client config:

npx -y @modelcontextprotocol/inspector --cli npx -y @modelcontextprotocol/server-filesystem@2.1.0 /path/to/folder --method tools/list

You should see the tools listed above. If this works but your client doesn't, the problem is in the client config, such as a wrong path or a missing cmd /c on Windows.

Troubleshooting

• The server stops right after starting: check node --version (2.x needs Node 24 or later) and that at least one folder is at the end of args. With no folders and a 2025-era client that doesn't support Roots, the server exits with status 1. For the client-side error, see MCP error -32000.
• "Access denied - path outside allowed directories": the AI asked for a path you didn't allow. Add the folder to args, or have it call list_allowed_directories first.
• Every tool call fails saying no directories are allowed: you started the server without folders and the client uses the 2026-07-28 protocol. Add at least one folder.
• `spawn npx ENOENT` on Windows: launch npx through cmd /c as the README does (shown above).
• Timeouts on a cloud-synced folder such as iCloud Drive: see slow or huge folders.

FAQ

Is the Filesystem MCP server safe to use?

It's limited to the folders you list, and v2.0.1 tightened how paths are checked. Within those folders it can overwrite and move files, so share as little as you can, keep the work in git, and use a read-only setup when the AI only needs to read.

Can I give it access to a single file?

Allowed directories are folders. With Docker you can mount a single file into /projects, which the README shows as an example.

Does it work with clients other than these?

It runs locally over stdio, so it needs a client that can start local MCP servers. A client that can only connect to remote servers can't start it.