Filesystem MCP ServerFeatured

What is Filesystem MCP Server?

Filesystem MCP Server is the reference filesystem MCP server from the Model Context Protocol project: a Node.js server that lets Claude and other MCP clients read, write, edit, move and search files, but only inside directories you allow.

It is published on npm as @modelcontextprotocol/server-filesystem and as the Docker image mcp/filesystem, from the official modelcontextprotocol/servers repository (MIT License). It runs locally over stdio, needs no API key, and every tool is marked as never reaching the internet or other external systems.

How to use Filesystem MCP Server?

Prerequisites: Node.js (for npx) or Docker. No account or API key is needed. The one required input is at least one allowed directory, given either as command-line arguments or by the client through MCP Roots.

Allowed directories as command-line arguments:

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

MCP Roots is the recommended method: clients that support Roots send their workspace folders to the server, which replaces the command-line list with them and picks up changes at runtime through roots/list_changed, with no restart.

Claude Desktop

Add this to claude_desktop_config.json, listing the folders you want to expose:

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

On Windows, launch npx through cmd /c:

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

With Docker, mount each directory under /projects. Adding ro makes a mount read-only for the server:

{
  "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",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

VS Code

Run MCP: Open User Configuration from the Command Palette, or create .vscode/mcp.json in your workspace to share the setup. Note that VS Code uses a servers key:

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

The Docker variant mounts ${workspaceFolder} to /projects/workspace and passes /projects as the argument.

Claude Code and Cursor

The README does not include steps for these clients, but both run the same stdio command. In Claude Code:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir

In Cursor, add the same mcpServers block shown for Claude Desktop to Cursor's mcp.json.

Key features of Filesystem MCP Server

• Sandboxed access: every operation is restricted to the allowed directories, and list_allowed_directories shows which ones are in force.
• Dynamic access control through MCP Roots, so the allowed folders follow the client's workspace without a restart.
• Text and media reading: read_text_file supports head/tail line limits, and read_media_file returns images and audio as base64 content blocks with their MIME type.
• Safe editing: edit_file makes targeted find-and-replace edits, keeps indentation and LF/CRLF line endings, returns a git-style diff, and supports a dryRun preview.
• Glob-style search and a recursive JSON directory_tree, both with exclude patterns.
• MCP tool annotations that mark each tool as read-only, idempotent or destructive, so clients can ask for confirmation before risky writes.
• Docker read-only mounts (ro) for folders the model may read but must not change.

Filesystem MCP Server tools

The server exposes 13 tools in three groups:

• Reading: read_text_file, read_media_file and read_multiple_files (a failed read does not stop the rest of the batch).
• Browsing and search: list_directory, list_directory_with_sizes (sortable by name or size, with totals), directory_tree, search_files, get_file_info (size, times, type, permissions) and list_allowed_directories.
• Writing: write_file creates or overwrites a file, edit_file applies selective edits, create_directory creates nested folders, and move_file moves or renames, failing if the destination already exists.

There is no delete tool. The README marks write_file, edit_file and move_file as destructive.

Use cases of Filesystem MCP Server

• Editing code or docs in a project folder: "In ~/projects/site, rename every getUser call in src to fetchUser and show me the diff first."
• Reviewing a folder: "List the largest files in ~/Downloads and tell me what they are."
• Organizing files: "Create a folder per year in ~/Documents/invoices and move each PDF into the right one."
• Reading images for analysis: "Open the screenshot in ~/Desktop/bug.png and describe the error."
• Finding files: "Search ~/notes for Markdown files about Kubernetes, excluding the archive folder."
• Building an MCP file system sandbox: giving a chat app the read-only context it needs to answer questions about local files.

Filesystem MCP Server vs alternatives

• Built-in file tools: coding agents such as Claude Code can already read and edit files in the working directory, so this filesystem MCP is most useful in chat clients like Claude Desktop that have no local file access of their own, or when you want a strict sandbox.
• Desktop Commander: a community Node.js MCP server that also runs terminal commands and manages processes. It is broader, and so it carries more risk than a file-only server.
• Memory MCP Server (Knowledge Graph): another reference server, for persistent facts across chats rather than file access. The two are often installed together.

Troubleshooting Filesystem MCP Server

• Server exits at startup with status 1: it was started with no directory arguments and the client does not support Roots. Add at least one allowed directory to args.
• "Access denied - no allowed directories": the client's roots were withdrawn or contain no valid paths. Open a workspace folder in the client, or add command-line directories.
• A path outside the sandbox is refused: this is by design. Call list_allowed_directories to see the current list, and remember that Roots replace the command-line directories completely.
• Docker cannot see your files: every directory must be mounted under /projects (by default), and /projects is passed to the server as its directory argument, as in the README examples.
• npx not found on Windows: use the cmd /c npx ... form shown above.