What this page answers
What Is @modelcontextprotocol/server-filesystem?
@modelcontextprotocol/server-filesystem is the official MCP filesystem server for local file operations. It lets a compatible MCP client read, list, search, create, move, and edit files through an explicit server boundary instead of giving the assistant unrestricted desktop access.
The server is powerful because the boundary is concrete. Directories can be supplied as command-line arguments, and newer clients can also provide allowed directories through MCP Roots. Searchers using the exact phrase @modelcontextprotocol/server-filesystem npx usually do not need an abstract MCP essay. They need the command, the JSON shape, the Windows fallback, and a safety model that tells them which local folders should stay out of scope.
Good first use
One repo, one docs folder, or one scratch folder where the assistant can list files and make a small reviewed change.
Bad first use
A full home folder, drive root, credential store, browser profile, or mixed cloud-sync folder with personal and work files.
How to Calculate a Safe Directory Scope
Choose the directory before the command
The allowed directory is the real permission decision. Start with a project folder, docs folder, or scratch folder. Do not begin with a home directory because it is convenient.
Match the client JSON shape
Claude Desktop commonly uses mcpServers. VS Code examples often use servers. The package name can stay the same while the outer JSON shape changes by host.
Account for Roots support
MCP clients that support Roots can provide or update allowed directories dynamically. When Roots are present, they replace the server-side allowed directories for that client session.
Restart and test the boundary
After saving config, restart the client, list the allowed directories, read one harmless file inside the folder, and confirm that unrelated paths stay outside the server boundary.
MCP Roots changes the directory model
The official filesystem server now describes two access-control methods: command-line allowed directories and MCP Roots. That makes the setup more flexible, but it also means users should verify what the client actually supplies after initialization.
Command-line arguments are still the most explicit way to see the allowed folders before launch.
Roots-capable clients can send directory roots during initialization and update them later.
When client Roots are supplied, the server treats those roots as the current allowed directories.
If no command-line directory and no usable Roots exist, the server cannot operate safely.
Command surface
Pick the command by folder scope
The package name is stable. The risk changes when you add more directory roots.
One project folder
npx -y @modelcontextprotocol/server-filesystem /Users/you/projects/my-appBest first run when the assistant should only inspect or edit one working tree.
Two narrow folders
npx -y @modelcontextprotocol/server-filesystem /Users/you/projects/my-app /Users/you/docs/referenceUse multiple roots only when each directory has a clear job and can be reviewed separately.
Windows wrapper
cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Users\You\Projects\my-appUse this when a Windows desktop client cannot launch npx from its own process environment.
Claude Desktop, VS Code, and Windows config examples
Use the client-specific outer object, then keep the directory list narrow. Replace placeholder paths before running the config. If the path does not exist on the machine that runs the MCP client, the server may start but the assistant will not get useful filesystem access.
Claude Desktop config
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/you/projects/my-app"
]
}
}
}Use this shape when the desktop client can launch npx directly.
VS Code config
{
"servers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"${workspaceFolder}"
]
}
}
}Use this shape when the client expects a servers object and can resolve workspaceFolder.
Windows Claude Desktop config
{
"mcpServers": {
"filesystem": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@modelcontextprotocol/server-filesystem",
"C:\\Users\\You\\Projects\\my-app"
]
}
}
}Use cmd /c when Windows app launch environment cannot find npx.
Worked Examples
Review one project folder
A developer exposes only a Next.js app folder, then asks the client to list package scripts and summarize source folders. The assistant can inspect the project, but it cannot wander into unrelated domains, personal files, or credential folders.
Test writes in a scratch folder
A team creates a scratch directory, exposes only that folder, writes a sample markdown file, renames it, and reads it back. Once review prompts feel correct, the team can repeat the setup with a real repository.
Add docs as a second root
A support agent needs code context and public docs. The command exposes the project folder and a docs reference folder. It does not expose the whole Documents directory, so invoices and private notes remain outside the boundary.
Do not expose
- Home folders and full drive roots
- Credential folders such as .ssh, password stores, browser profiles, and token caches
- Cloud sync roots that mix personal documents, invoices, contracts, and work files
- Production backups, tax records, client archives, or private export folders
- Downloaded archives or generated folders that have not been inspected
Common errors and fixes
The server starts, but no files appear.
The path is wrong, the placeholder was not replaced, or the client was not restarted.
Use an absolute local directory, save config, fully quit the client, then reopen it.
npx works in Terminal, but not in the desktop client.
The app inherited a different PATH than your shell, or Windows needs cmd /c.
Use the Windows wrapper on Windows, or point the client to the full npx path if required.
A sibling folder is unavailable.
Only one directory root was allowed at startup or supplied by Roots.
Add the second folder deliberately, restart or update Roots, then list allowed directories.
The setup feels risky for a real repository.
The folder scope is too broad or write behavior has not been tested.
Move back to a scratch folder, test dry-run or small writes, then graduate to the real project.
The command launches but edits are surprising.
The assistant has file tools, but no human review checkpoint.
Require diff previews, use narrow prompts, and keep generated changes inside reviewed folders.
Filesystem vs Everything vs Memory
Passing an MCP command test is not the same as choosing the right server. Route users by what the server can touch after launch.
Filesystem
Use for local files
Choose this when the task needs project files, docs, scratch output, or repository edits inside explicit directory roots.
Everything
Use for client smoke tests
Choose the reference server when you need to prove an MCP client can start a server before connecting real data.
Memory
Use for persistent knowledge
Choose Memory when the workflow needs a local knowledge graph and a review path for retention and deletion behavior.
Frequently Asked Questions
What is @modelcontextprotocol/server-filesystem?
It is the official Model Context Protocol filesystem server for local file operations inside directories that are explicitly allowed at startup or supplied by an MCP client through Roots. It is useful when an MCP client needs scoped file access for a project, docs folder, or scratch workspace.
What is the basic npx command for the filesystem MCP server?
Use npx -y @modelcontextprotocol/server-filesystem followed by one or more allowed directory paths. The path matters as much as the package name because it defines the server permission boundary.
Can the filesystem server start without a directory argument?
Only when the MCP client supports Roots and supplies allowed directories during initialization. If there are no command-line directories and no usable Roots, the official server will not have a directory boundary to operate inside.
Should I expose my whole home folder?
No. Start with one project folder, one documentation folder, or one scratch folder. Avoid home folders, drive roots, credential folders, browser profiles, and cloud sync folders that mix personal and work material.
How do I configure this server on Windows?
If the desktop MCP client cannot find npx on Windows, use command set to cmd and args starting with /c, npx, -y, @modelcontextprotocol/server-filesystem, then the exact allowed Windows path.
Is server-filesystem safer than server-everything?
They solve different jobs. server-everything is a reference server for client smoke tests. server-filesystem is a real local file access server, so it needs stricter directory review and safer first-run prompts.
What should I test after adding the server?
Restart the MCP client, ask it to list allowed directories, ask it to read a harmless file inside the allowed folder, and confirm that a path outside the allowed folder is unavailable before trying edits.