How to Install the Filesystem MCP with Claude Code (2026)
A. Frans
Published June 14, 2026
Table of Contents
- 01What the Filesystem MCP actually does
- 02Prerequisites
- 03Step 1: Add the server with the CLI
- 04Step 2: Or edit the config by hand
- 05Step 3: Verify it loaded
- 06Step 4: Put it to work
- 07The security part nobody should skip
- 08Filesystem MCP vs other ways to extend Claude
- 09A worked example
- 10Troubleshooting
- 11FAQ
Claude Code already reads and writes files in your project directory. So why install a Filesystem MCP server at all? Because it lets Claude reach files outside your current project (a shared assets folder, a downloads directory, a sibling repo) under directory limits you set explicitly. It turns "Claude can see this one folder" into "Claude can work across the exact folders I allow, and nothing else."
This guide gets you from nothing to a working, scoped Filesystem MCP in about ten minutes, with the security parts that most tutorials gloss over.
What the Filesystem MCP actually does
The Model Context Protocol (MCP) is a standard way to give Claude tools and data sources. The official Filesystem server exposes file operations (read, write, create, move, search, list) but only inside directories you whitelist when you start it. That whitelist is the whole security model. Outside those paths, the server simply can't see anything.
| Capability | Filesystem MCP | Plain Claude Code |
|---|---|---|
| Read/write in current project | Yes | Yes |
| Access folders outside the project | Yes (whitelisted) | No |
| Operate across multiple repos at once | Yes | One project at a time |
| Directory scoping / sandboxing | Explicit, enforced | Project root only |
| Search across allowed dirs | Yes | Limited to project |
Prerequisites
- Claude Code installed and working
- Node.js 18+ (the server runs via
npx) - Two minutes to decide which directories you'll allow. Do this deliberately, not on autopilot
Check Node:
node --version
If that prints v18 or higher, you're set.
Step 1: Add the server with the CLI
The cleanest install is one command. Claude Code's mcp add writes the config for you. Pass the directories you want to whitelist as the final arguments:
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/you/projects /Users/you/Documents/assets
Everything after the -- is the command Claude Code runs. The two paths at the end are the only directories the server will touch. Add or remove paths to match exactly what you need, and nothing more.
On Windows, use Windows-style paths:
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem C:\Users\you\projects C:\Users\you\Documents\assets
Step 2: Or edit the config by hand
If you prefer to see the config, add the server to your MCP settings file directly. The block looks like this:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/you/projects",
"/Users/you/Documents/assets"
]
}
}
}
Each path in args after the package name is a whitelisted root. Leave out any directory you don't want Claude reaching. Save the file and restart Claude Code so it picks up the change.
Step 3: Verify it loaded
Back in Claude Code, list your servers:
claude mcp list
You should see filesystem and a connected status. If it's missing, the usual culprits are a typo in the path, a path that doesn't exist, or forgetting to restart. Inside a session, /mcp shows the connected servers and the tools they expose.
Step 4: Put it to work
Now Claude can operate across your whitelisted folders. Some prompts that show what changes:
- "Find every PNG in my assets folder larger than 2MB and list them by size." This reaches outside the project.
- "Move all the invoices from my Downloads folder into Documents/invoices, renamed by date." Cross-directory file operations in one prompt.
- "Read the README from my other repo at projects/api-server and summarize how its auth works." Pulling context from a sibling project without leaving this one.
- "Compare the config files in projects/web and projects/api and tell me what drifted." Two repos compared at once.
That last pattern is the real unlock. Plain Claude Code sees one project; the Filesystem MCP lets it reason across several at the same time.
The security part nobody should skip
A tool that reads and writes files is exactly the kind of thing you scope tightly. Three rules:
Whitelist the narrowest set of directories that does the job. Don't hand it your entire home folder because it's convenient. If the task needs two folders, allow two. Every extra path is extra blast radius if a prompt goes sideways.
Never whitelist directories with secrets. Keep .ssh, .aws, password stores, and credential files out of the allowed paths entirely. The server can't leak what it can't see, so keep them out of scope.
Watch write and move operations. Reading is low-stakes. Moving, renaming, and deleting are not. When Claude proposes a file operation that changes or removes data, read the plan before approving it. Keep your work in version control so anything unexpected is recoverable.
This is the same diligence you'd apply to any tool with filesystem access. For the broader picture on vetting what you install, see why agent skill security matters and how to audit them.
Filesystem MCP vs other ways to extend Claude
People often install the Filesystem MCP when they actually want something else. Three quick distinctions:
Versus built-in project access. Claude Code already reads and writes inside your open project. If that's all you need, skip the MCP. The server only earns its place when you want reach into folders outside the project root or across several projects at once.
Versus an agent skill. A skill teaches Claude how to do a task, like building a spreadsheet or parsing a PDF. The Filesystem MCP gives Claude access to files. They solve different problems and often pair: a skill does the work, the MCP supplies the files it works on.
Versus a more specialized MCP. If your real goal is talking to a database, a Postgres MCP is the right tool, not the Filesystem server pointed at a data directory. Match the server to the system you're actually working with. The Filesystem MCP is for plain files and folders, nothing more.
The rule of thumb: reach for the Filesystem MCP when your task is fundamentally about moving, reading, or organizing files across locations your project can't normally see.
A worked example
Say you keep a folder of client invoices in Downloads and want them sorted by month into Documents. With the Filesystem MCP scoped to those two directories, the whole job is one prompt:
Look through my Downloads folder for PDF invoices, read the date on each,
and move them into Documents/invoices/YYYY-MM folders, creating the month
folders as needed. Show me the plan before moving anything.
Claude lists what it found, proposes the moves, and waits. You approve, and the files land where they belong. That "show me the plan first" line is the habit to keep on every file operation. It turns a risky bulk move into something you can review before it happens.
Troubleshooting
Server shows "failed" in the list. Almost always a bad path. Confirm every whitelisted directory exists and is spelled correctly, then restart Claude Code.
"Access denied" when Claude tries a file. The file is outside your whitelisted roots. That's the server working as designed. Add the directory only if you genuinely want access.
npx can't find the package. Check your Node version (18+) and internet connection; npx -y fetches the package on first run.
FAQ
Is the Filesystem MCP server official? Yes. @modelcontextprotocol/server-filesystem is maintained as a reference server under the Model Context Protocol project. That makes it one of the safer MCP servers to run, but you still scope its directories tightly.
Does this replace Claude Code's built-in file access? No, it extends it. Built-in access covers your current project. The Filesystem MCP adds reach to other whitelisted folders and lets Claude work across multiple locations in one session.
Can it delete my files? It can perform delete and move operations within whitelisted directories if you approve them. Keep your work in version control and review any destructive operation before confirming it.
How do I add or remove an allowed directory later? Edit the args list in your config (or re-run claude mcp add with the new path set) and restart Claude Code. The change takes effect on the next launch.
Do I need this if I only ever work in one project folder? Probably not. Claude Code's built-in access already covers a single project. The Filesystem MCP is for cross-folder and multi-repo work. Compare it with other extension options in our skills vs MCP vs GPTs guide.
Can I run more than one MCP server at once? Yes. Most setups run several side by side, each scoped to its own job. You might pair the Filesystem MCP with a Postgres MCP and a GitHub MCP in the same config. They show up together under /mcp, and Claude picks the right tool per request. Keep each one's permissions as narrow as the task allows so a broad grant on one doesn't undercut the careful scoping on another.
Does the whitelist apply to subfolders too? Yes. Whitelisting a directory grants access to everything beneath it, recursively. That's convenient and also why you scope tightly: pointing the server at your home folder would expose every subfolder under it, secrets included. Allow the specific working directories you need, not their broad parents.
Share this article
📄Related Articles
Get More AI Tool Guides
New comparisons and guides every week. Join thousands of professionals staying ahead of the AI curve.