Filesystem MCP Server

Quick answer: The Filesystem MCP server gives Claude Code and Cursor scoped read-write access to specific folders on your machine. Install with one npx command, pass the allowed paths as arguments, and restart the host app. No API key, no cloud round-trip, free to run.

The Filesystem MCP server is the most common first install for anyone wiring Claude Code or Cursor up to real work. It hands your AI assistant a small, auditable set of disk operations - read, write, list, search, watch - scoped to directories you approve at startup. The server runs locally over stdio and talks to the host IDE using the Model Context Protocol.

If you have been copy-pasting code between a chat window and your editor, this is the upgrade. The assistant can now open the exact file, apply a patch, and run a search across your project without you babysitting the clipboard.

What this server does

The Filesystem server exposes a focused set of tools that map to the operations you already know from your shell:

• Read a file as UTF-8 text
• Write a file to create or overwrite it
• List a directory with type, size, and modified timestamps
• Search subtrees for filename patterns or string occurrences
• Watch a directory and stream change notifications while the session is open
• Move or rename files while preserving Unix permissions
• Delete files and empty directories with an explicit confirmation

Everything is gated by the allowlist you pass as command-line arguments. If you start the server with /Users/you/projects/myapp, the assistant cannot read your SSH keys, your Downloads folder, or anything under a sibling project directory. This scoping is the single most important security property of the server and the reason teams are willing to install it at all.

Installing Filesystem MCP Server

The server ships as an npm package at @modelcontextprotocol/server-filesystem. You do not need to install it globally - npx -y fetches it on first use and caches it afterward. Node.js 18 or newer is the only prerequisite, and if you already run Claude Code or Cursor you likely have that installed.

Test the install from a terminal first:

npx -y @modelcontextprotocol/server-filesystem /tmp

The process will start and wait for MCP protocol messages on stdin. Press Ctrl+C to exit. If you see an ENOENT error or Node crashes, upgrade your Node install before continuing.

Configuring for Claude Code

Open the Claude Code settings file - on macOS that is ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows %APPDATA%\Claude\claude_desktop_config.json, and on Linux ~/.config/Claude/claude_desktop_config.json. Add a server entry under mcpServers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    }
  }
}

You can list multiple allowlisted paths by appending more arguments. Keep the list tight. Granting access to your home directory defeats the purpose of the sandbox and puts personal data within reach of any tool call the assistant decides to make.

Restart Claude Code after saving. The server will appear in the MCP panel and the assistant will gain access to the filesystem tools on the next turn.

Configuring for Cursor

Cursor reads MCP servers from its own settings. In Cursor, open Settings and search for MCP. Add a new server with the same shape as above:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/code"]
    }
  }
}

Cursor also supports per-workspace MCP configuration in a .cursor/mcp.json file at the project root. That is the cleaner pattern when you want different allowlists for different projects. Commit the file to the repo if your whole team uses the same setup.

Example prompts and workflows

Once the server is live, the phrasing you use in chat changes. Instead of describing your code, point at it. A few prompts that work well:

"Read src/components/Button.tsx and suggest an a11y-aware refactor."

"Search the repo for every call to the old getUser helper and list the files."

"Create a new file at scripts/backfill.ts that reads CSV rows and writes them to the users table."

"List the 10 largest files under public/ so I can pick what to compress."

The assistant will call the matching tool, show you the proposed change, and wait for approval before writing. You can batch several reads and edits inside a single prompt, which is how most people end up using the server after a few days.

A workflow pattern worth adopting: start the session with a high-level request like "audit the auth flow for missing error handling," let the assistant crawl the directory, then have it produce a markdown report before making any edits. You keep full control of the write step, and the read step is where most of the value lands.

Troubleshooting common issues

The server logs to stderr, so if something is off the first stop is the MCP server output panel in Claude Code or Cursor. The usual suspects are a typo in the allowlisted path, a permissions error because the path belongs to another user, and Node being too old.

If file operations succeed but the assistant does not seem to notice, check the MCP tool usage indicator. Some hosts collapse tool output by default and the assistant may be waiting on a human to confirm a write it already proposed.

On Windows, use forward slashes or escaped backslashes in the JSON config. C:\\Users\\you\\code works, C:\Users\you\code produces an invalid JSON parse error.

On macOS, if the server never starts from Claude Desktop, it is usually because the installed Node binary is not in the PATH that the GUI launches with. Setting an absolute path to the npx binary in the command field fixes it without a system-wide PATH change.

Finally, if the assistant refuses to run a tool, check the MCP server logs for an access-denied error. That means the path the assistant asked for was outside your allowlist - add the path to the arguments and restart.

Alternatives and when to consider them

The Filesystem MCP is the right default for one machine, one developer, and a small number of directories. It falls short in a few specific scenarios.

If you need network-mounted code or shared drives, look at a remote filesystem server or the SSH MCP community servers. They add a round-trip but keep the same tool shape.

If you want the assistant to see git state - current branch, uncommitted changes, blame - pair Filesystem with the GitHub MCP server or a dedicated git MCP. Filesystem reads the working tree but has no concept of history.

If you are working on content heavy projects with many binary assets, consider the Google Drive MCP or a cloud storage server instead. Filesystem can read any byte but does not know how to interpret images, Word documents, or PDFs without help from another tool.

For remote execution against a sandbox like Docker or a VM, the E2B or Docker MCP servers are closer to what you want. Filesystem touches the host disk directly and has no notion of containerized workspaces.

For most day-to-day coding work, you want Filesystem first and add the others as real needs show up. Start with one directory, widen the allowlist only when a specific task demands it, and keep your sensitive folders - keys, credentials, tax returns - well outside any path the server can see.