Filesystem MCP server in Cursor a fence around file access.
Give Cursor's agent fenced access to directories outside the open project — mcp-server-filesystem runs locally via npx and is configured in one mcp.json entry.
Cursor's agent handles the project you have open; mcp-server-filesystem handles everything you deliberately let it reach beyond that. The server (@agent-infra/mcp-server-filesystem on npm, from ByteDance's ui-tars-desktop monorepo, 36.3k stars) exposes read, write, and search tools that refuse any path outside an allow-list you set at startup.
That makes it the right tool when a Cursor task needs a reference directory, a downloads folder, or a second project — without opening those as workspaces.
Pick the config scope
Cursor merges MCP servers from ~/.cursor/mcp.json (every workspace) and .cursor/mcp.json (this repo only). For a filesystem server the project file is often the better choice: the allowed directories that make sense usually depend on the project you're in, and a project-scoped config keeps the grant from following you everywhere.
Either file takes the same shape, and Cursor Settings > MCP edits them through a UI if you prefer.
The mcp.json entry
This is a stdio server — Cursor spawns it with npx, so Node 18+ must be installed. Everything after --allowed-directories is the access fence:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@agent-infra/mcp-server-filesystem@latest",
"--allowed-directories",
"/Users/you/reference"
]
}
}
}Enable it and watch the tool count
Open Cursor Settings > MCP after saving. The filesystem server appears with a toggle — switch it on, and within a few seconds the status dot should go green with a tool count beside it. Those tools (file reads, writes, directory listing, search) are also published on the server's live Loomal listing at https://loomal.ai/marketplace/mcp-server-filesystem if you want to review them before enabling.
First agent test: "using the filesystem tools, list what's in /Users/you/reference and read the README there." Naming the server nudges the model to use the tools rather than apologize about file access.
Scope the allow-list like it matters
It does: Cursor's agent mode can chain many tool calls per task, and the allowed-directories list is the only boundary the server enforces. Grant the specific folders the work needs — multiple paths are fine as extra args — and keep write-sensitive locations out unless writing is the point. Absolute paths only; the server inherits a working directory you didn't choose, so relative paths land somewhere surprising.
When the agent reports a path as not permitted, that's the fence working. Extend the list deliberately instead of widening it to / out of frustration.
Troubleshooting in Cursor
No server in the MCP settings list: mcp.json didn't parse — Cursor drops invalid files without complaint. Validate the JSON and restart Cursor.
Red or yellow dot: the spawn failed. Open the Output panel and select the MCP Logs channel; "npx: command not found" means Cursor's environment lacks your Node installation (launching Cursor from a terminal inherits the right PATH), while a 404 from npm means the package name lost its @agent-infra/ scope.
Green dot but zero tools, or tools that error on every call: re-check the args array — each flag and each path must be its own array element, and the directory after --allowed-directories must exist before the server starts.
FAQ
How do I install the filesystem MCP server in Cursor?
Add a filesystem entry to .cursor/mcp.json (or ~/.cursor/mcp.json) with command npx and args running @agent-infra/mcp-server-filesystem@latest plus --allowed-directories and absolute paths. Enable the toggle in Cursor Settings > MCP and wait for the green dot.
Why would Cursor need this if it already edits my project?
For everything outside the open workspace. The server lets the agent read a reference folder, process files in a data directory, or write output elsewhere — under an explicit allow-list, which is safer than opening those locations as full workspaces.
Global or project mcp.json for this server?
Project (.cursor/mcp.json) usually fits better, because sensible allowed directories differ per project and the grant stays contained. Use the global file only for a directory you genuinely want reachable from every workspace, like a personal notes folder.
The server is enabled but every file operation fails — what's wrong?
Almost always the allow-list: the path the agent tried isn't under --allowed-directories, or the configured path was relative and resolved elsewhere. Switch to absolute paths, confirm the directory exists, then restart the server from Cursor's MCP settings.
More MCP servers for Cursor.
Browse live-probed tool lists on the Loomal marketplace.