Filesystem MCP server in Claude Code scoped file access, one command.
mcp-server-filesystem gives Claude Code controlled read/write/search access to directories outside your project — added with a single claude mcp add command or a project .mcp.json.
mcp-server-filesystem (published as @agent-infra/mcp-server-filesystem from ByteDance's ui-tars-desktop monorepo, 36.3k stars) exposes filesystem operations — read, write, search, directory listing — as MCP tools, fenced to directories you explicitly allow.
Claude Code already edits files in your working directory, so the honest pitch here is different: this server is for the directories your session shouldn't fully own. Mount your notes folder read-heavy, a shared assets directory, or a second repo — without widening Claude Code's own workspace.
When Claude Code needs this server
Three cases come up in practice. You want the agent reading reference material that lives outside the repo (design docs, a sibling project). You want a deliberately narrow grant — one directory, nothing else — instead of broadening the session's working scope. Or you're standardizing one MCP toolset across clients that don't have native file tools, and Claude Code should match.
The server's exact tool list is published on its live Loomal listing at https://loomal.ai/marketplace/mcp-server-filesystem.
Fastest path: claude mcp add
Claude Code's CLI registers MCP servers without touching a config file by hand. Everything after the double dash is the literal command Claude Code will spawn:
claude mcp add filesystem -- \
npx -y @agent-infra/mcp-server-filesystem@latest \
--allowed-directories ~/notesProject-scoped alternative: .mcp.json
To version the server with a repo so every collaborator gets it, commit a .mcp.json at the project root instead. Claude Code prompts each user to approve project-scoped servers on first use:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@agent-infra/mcp-server-filesystem@latest",
"--allowed-directories",
"./docs"
]
}
}
}The --allowed-directories fence
Every tool call the server handles is checked against the allowed list; paths outside it are refused. Pass the narrowest set of directories that covers the task — and prefer absolute paths or paths you're certain resolve from where the server starts, since a relative path that resolves somewhere unexpected is the most common "why can't it see my files" report.
This fence is the server's security model. It runs with your user's permissions, so the allowed list is the only thing standing between the agent and anything your account can write.
Verify and troubleshoot
Run claude mcp list in the terminal to see registered servers, or type /mcp inside a session to check connection status and browse the filesystem server's tools. Then ask Claude Code to list the contents of an allowed directory — a real listing confirms the spawn, the package, and the fence all work.
If the server shows as failed: confirm npx runs in your shell (Node 18+ required) and that the package name is exact — @agent-infra/mcp-server-filesystem, easy to confuse with similarly named filesystem servers. If tools work but every path is denied, your allowed directory didn't resolve where you thought; switch to an absolute path. After editing .mcp.json directly, start a fresh session so the file is re-read.
FAQ
How do I install the filesystem MCP server in Claude Code?
Run claude mcp add filesystem -- npx -y @agent-infra/mcp-server-filesystem@latest --allowed-directories <dir>, or commit the equivalent entry in a project .mcp.json. Verify with claude mcp list or the /mcp command in a session.
Doesn't Claude Code already have file access?
Yes, within your working directory. This server is for controlled access beyond it — a notes folder, a sibling repo, shared assets — where you want an explicit, narrow grant via --allowed-directories rather than a wider workspace.
What's the difference between claude mcp add and .mcp.json?
claude mcp add registers the server in your user config, following you across projects. A .mcp.json in the repo root is project-scoped and shareable — teammates get prompted to approve it on first use. Same server either way; pick the scope that fits.
Why does the server refuse paths I know exist?
The path falls outside --allowed-directories, usually because a relative path resolved against an unexpected working directory. Re-add the server with absolute paths in the allowed list and the refusals stop.
More MCP servers for Claude Code.
Browse live listings with probed tool lists on the Loomal marketplace.