Filesystem MCP Server

The Filesystem MCP Server is the reference implementation maintained by Anthropic as part of the official MCP server collection. It is the most widely installed MCP server in the ecosystem — currently pulling over 170,000 weekly downloads on npm — and the default starting point for any developer adding MCP capabilities to their IDE.

What makes it essential

Every AI coding assistant needs file access. Without this server (or an equivalent), your assistant can only work with content pasted into the chat window. With it, the assistant can navigate your project, read source files, make edits, and manage directories — all while respecting the path boundaries you configure.

Multiple directory access

You can pass more than one path as arguments to grant access to multiple directories in a single server instance:

jsonCOPY
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects/app",
        "/Users/you/shared-libs"
      ]
    }
  }
}

Docker installation (sandboxed)

The official image supports read-only mounts via the ro flag, making it a good option when you want stricter isolation:

jsonCOPY
{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--mount", "type=bind,src=/Users/you/projects,dst=/projects/app",
        "--mount", "type=bind,src=/Users/you/read-only-dir,dst=/projects/ref,ro",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

All directories must be mounted under /projects when using Docker. The ro flag makes a mount read-only at the OS level — the server cannot write to it even if the AI tries.

Security considerations

The server only accesses directories you explicitly pass as arguments. It does not have access to your entire filesystem by default. Always scope the path to the specific project directory you're working with:

• Good: /Users/you/projects/my-app
• Risky: /Users/you (exposes everything under your home directory)
• Dangerous: / (never do this)

Common setup issues

"npx not found" on macOS/Linux If your IDE can't find npx, use the full path. Run which npx in your terminal and use the absolute path in the config:

jsonCOPY
"command": "/usr/local/bin/npx"

"Permission denied" errors The server runs as your user. If your project directory has restricted permissions, the server will fail. Ensure your user has read/write access to the configured path.

Windows path format On Windows, use double backslashes or forward slashes in your path args:

jsonCOPY
"args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\you\\projects"]

Server starts but AI doesn't use file tools Check if you have too many MCP servers enabled. Cursor limits tool discovery when more than ~40 tools are registered. Disable servers you're not actively using.

Zed: server not appearing Zed uses context_servers (not mcpServers) with a nested command.path structure. See the Zed config tab above — the format is different from every other IDE. Also note Zed only supports stdio transport natively; to use an HTTP/SSE server you need the mcp-remote bridge package.

Continue: config not picked up Continue reads from ~/.continue/mcpServers/ (note the plural). Drop a .json file there and restart your IDE. Alternatively you can add an mcpServers array directly in ~/.continue/config.yaml. The format uses an array (not an object) — a common source of silent failures when copying from Cursor or Claude Desktop.