What Is @modelcontextprotocol/server-filesystem?
@modelcontextprotocol/server-filesystem is the official MCP filesystem server for local file operations. It lets an MCP client work with files through a standard server boundary instead of giving the assistant unrestricted operating-system access. The server is launched with one or more explicit directory arguments, and those directories become the access roots for the session.
This page exists for searchers who already know the package name and need the working npx setup shape. It covers the direct command, Claude Desktop JSON, VS Code JSON, Windows cmd /c wrapper, safe directory choices, and the common mistakes that make filesystem MCP setup look broken.
The server is useful for local coding, documentation, repo inspection, controlled note folders, and scratch work. It is not a reason to expose every file on a machine. A good filesystem MCP setup starts from the smallest directory that can complete the job, then expands only when a real task needs another folder.
How to Calculate the Safe Filesystem NPX Setup
Calculate the setup by combining four inputs: the package name, the client config shape, the operating system wrapper, and the allowed directory list. The package name should stay exact: @modelcontextprotocol/server-filesystem. The client shape changes between Claude Desktop and VS Code. The wrapper changes on some Windows clients. The directory list is the highest-risk part because it decides the real permission boundary.
Step 1
Pick the allowed directory first
The directory argument is the permission boundary. Start with a single project, docs, or scratch folder. If the task needs a second folder, add it deliberately and write down why that folder belongs in scope.
Step 2
Choose the client config shape
Claude Desktop commonly uses an mcpServers object. VS Code MCP examples use a servers object. The command and package can stay the same while the outer JSON changes for each client.
Step 3
Use the Windows wrapper only when needed
On Windows, some desktop clients launch commands more reliably through cmd /c. That wrapper should not change the package name or expand the allowed directory scope.
Step 4
Restart and test with a read-only prompt
After saving config, restart the MCP client and ask it to list files inside the allowed folder. Then ask it about an outside path and confirm the request is refused or unavailable.
Claude Desktop and VS Code Config Examples
Use the client-specific outer object, then keep the command narrow. Replace every placeholder path before running the config. If the path does not exist on the machine that runs the MCP client, the server can launch but the client will not get useful filesystem access.
Claude Desktop config
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/you/projects/my-app"
]
}
}
}VS Code config
{
"servers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"${workspaceFolder}"
]
}
}
}Windows Claude Desktop config
{
"mcpServers": {
"filesystem": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@modelcontextprotocol/server-filesystem",
"C:\\Users\\You\\Projects\\my-app"
]
}
}
}Worked Examples
Example 1: Review one project folder
A developer wants an MCP client to inspect a Next.js app. The safe command exposes only the app folder, not the full workspace. The first prompt asks the client to list package scripts and summarize source folders. The client can read inside the project but cannot wander into unrelated domains, personal files, or credential folders.
Example 2: Use a scratch folder before real edits
A team wants to test write behavior. They create a scratch folder and expose only that folder. The MCP client writes a sample markdown file, renames it, and reads it back. Once the approval prompts and file diffs feel correct, the team can repeat the setup with a real project folder.
Example 3: 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 entire documents directory. That lets the agent compare code and docs while keeping unrelated contracts, invoices, and personal notes outside the MCP boundary.
Common Errors and Fixes
The server starts, but the client sees no files.
The allowed path is wrong, the path contains an unresolved placeholder, or the client was not restarted.
Replace the path with an absolute local directory, save config, fully quit the client, then reopen it.
npx works in Terminal, but not in the desktop client.
The desktop client has a different PATH than your shell, or Windows needs cmd /c.
Use the Windows wrapper on Windows, or point command to the full npx path if your client requires it.
The agent cannot access a sibling folder.
Only one root was allowed at startup.
Add the second folder as another explicit allowed path, then restart the MCP client.
The setup feels risky for a real repository.
The folder scope is too broad or write behavior has not been tested.
Switch to a scratch folder first, test read and write prompts, and only then move to the real project folder.
Filesystem vs Everything
Use server-everything when you are testing general MCP client behavior and protocol surfaces. Use server-filesystem when the job specifically requires local file access. The first one is a reference server for broad protocol checks. The second one touches local files, so it deserves a more concrete permission review.
In production-like workflows, the filesystem server should usually be paired with a visible review step such as Git diff, pull request, or a human-approved change list. That keeps local file automation useful without turning every assistant session into an unrestricted desktop automation surface.