Third-party toolUpdated 2026.11.16

Filesystem MCP Setup: Claude Code, Codex, Cursor and Fixes

Filesystem MCP installation and getting started: client setup or a local workflow, three practical examples, tested findings, common errors, costs and alternatives.

Aaron recommends Open official GitHub

Filesystem MCP exposes file operations inside configured directories to an MCP client. Start with a dedicated test directory and read-only mode to verify the boundary. It is useful when your client needs file access through MCP, but adds little when the client already has suitable native workspace tools.

Install and choose a working environment

Tool version 2.3.0. Documentation checked 2026-11-16. The upstream source snapshot and installed package are pinned separately; the snapshot is not claimed to be the package’s release commit.

node --version
npm install --ignore-scripts --save-exact @modelcontextprotocol/server-filesystem@2.3.0

Replace /absolute/path/test-project with an existing disposable directory. On Windows, an absolute path can use forward slashes, for example C:/mcp-demo.

These settings use the officially documented stdio configuration format. They are documentation-based and were not tested inside the three client apps. Tool version: 2.3.0; client documentation checked 2026-11-16 (rolling docs, no fixed client release claimed).

Claude Code

claude mcp add --transport stdio mcp-filesystem -- npx -y @modelcontextprotocol/server-filesystem@2.3.0 --read-only /absolute/path/test-project
claude mcp get mcp-filesystem

Open /mcp in Claude Code and verify the server and discovered tools.

Claude Code official MCP configuration

Codex

codex mcp add mcp-filesystem -- npx -y @modelcontextprotocol/server-filesystem@2.3.0 --read-only /absolute/path/test-project
codex mcp list

Start a fresh session and check the server’s tools before running the examples.

Codex official MCP configuration

Cursor

Merge this entry into the project’s .cursor/mcp.json; preserve other entries. Enable it in Cursor’s MCP settings and inspect the tool list.

{
  "mcpServers": {
    "mcp-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem@2.3.0",
        "--read-only",
        "/absolute/path/test-project"
      ]
    }
  }
}

Cursor official MCP configuration

On Windows, if npx fails to launch, use command cmd with args beginning /c, npx, then the same arguments. For example, the CLI launch portion becomes -- cmd /c npx -y <the pinned package above>. Do not change package versions while troubleshooting.

Three practical uses

1. Check the allowed directories

Call list_allowed_directories, then list the test directory. Do not create, move or delete files.

Expected: a response that follows the stated scope and exposes the requested source or tool result. Verify those references before acting.

2. Answer from a source file

Read README.md in the allowed test directory with read_text_file. Quote the installation steps and stay inside that directory.

Expected: a response that follows the stated scope and exposes the requested source or tool result. Verify those references before acting.

3. Verify read-only discovery

List the server tools and confirm write_file, edit_file and move_file are absent. Do not test against production files.

Expected: a response that follows the stated scope and exposes the requested source or tool result. Verify those references before acting.

What our tests established

The 2.3.0 stdio test read an allowed file, rejected an outside path and hid write tools with --read-only. It used Node 24 and synthetic files; the three AI-client interfaces were not locally tested.

Tests were run by Codex on synthetic data; no claim of the owner personally testing or reviewing this guide. Examples added above are documentation-based unless included in that recorded scope.

Common errors and fixes

Server disconnected

Check Node and the executable path. On Windows, use the documented cmd wrapper when npx cannot launch.

Access denied or outside directory

Check the resolved path against the allowlist; do not broaden access to the entire home directory.

Write tools missing in read-only mode

This is expected. If writing is required, create a separate scoped configuration and back up inputs.

Limits, costs and license

MIT. Model/client costs are separate. Verify configured directories and client roots. Read-only mode prevents file mutation, not transmission of file contents to a model.

When to choose an alternative

FAQ

Why does Filesystem MCP disconnect?

Check the runtime, launch command and allowed directory; isolate the server with Inspector.

Does Claude Code need an extra filesystem server?

Prefer existing native tools unless you need MCP integration or a different access boundary.

Can I run it in Docker?

The official guide supports containers; distinguish host paths from mounted container paths.

Official sources

To inspect the connection separately from tool responses, use MCP Inspector's diagnostic workflow. For structured memory data, compare Memory MCP's persistence.

Subscribe to AI tool picks and practical advice

Get worthwhile tool picks, test findings and important updates in your inbox.

Get a monthly-updated list of AI tools and Skills right away. We email when there are worthwhile tool picks, test findings or important updates. Unsubscribe anytime. Privacy

Almost done: check your inboxClick the button in the confirmation email and you will get the download link for the tool list. If you do not see it, check your spam or Promotions folder.

Or follow us on: