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
-
For a one-time repository snapshot: Repomix.
-
For a small explicit file selection: files-to-prompt.
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.