Filesystem MCP Server: Let AI Read Local Files

⏱️ 3 min read 🔌 MCP Server

What it is: One of the original reference MCP servers, @modelcontextprotocol/server-filesystem, still actively maintained in the modelcontextprotocol/servers repo. It gives an agent read (and, if you allow it, write) access to directories you explicitly list as command-line arguments — nothing outside that allowlist is reachable, by design.

Quick answer: Run npx -y @modelcontextprotocol/server-filesystem /path/to/project, listing every directory you want accessible as a separate argument. The allowlist is the entire security model here — the server refuses paths outside it, so the real decision is simply which directories you pass in.

Why it matters for data work

Most local data work — a folder of CSV exports, a set of notebooks, a project's config files — doesn't live behind an API at all, it's just files on disk. This server is the most direct way to let an agent work with them: list a directory, read a file's contents, search for a pattern across a project, write out a cleaned version. It's also the substrate a lot of agentic coding tools build on.

Install & configure

Every directory you want the agent to reach is passed as a separate argument — there's no config-file allowlist, just the process args:

# Claude Code
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem \
  /Users/you/projects/analytics /Users/you/Downloads/exports

// Claude Desktop / Cursor config
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem",
               "/Users/you/projects/analytics", "/Users/you/Downloads/exports"]
    }
  }
}

Use absolute paths — relative paths resolve against the process's working directory, which is rarely what you expect from a GUI-launched client like Claude Desktop.

Which directories should the agent actually see?

This is the only real decision the server asks of you, and it matters more than it looks like it does. Passing your entire home directory "to be safe" defeats the point of the allowlist — it hands the agent your SSH keys, browser profiles, other clients' credentials, everything. Scope it to the specific project or data folder the task needs, add more directories later if a real need comes up, and keep anything sensitive (secrets, other projects, personal files) out of the allowlisted tree entirely.

How do I keep it safe?

Beyond directory scoping, remember the server will write files if you ask the agent to and the directory is writable — treat it like giving a very literal-minded intern shell access to that folder. Keep the allowlisted directories under version control where practical, so an unwanted change is a git diff away from being caught and reverted, and avoid allowlisting a directory that also holds files a separate, untrusted process might write to (a shared download folder, for instance) since the agent will read whatever's there as legitimate input.

Troubleshooting

Common issues:

"Access denied" for a path you expect to work: the path isn't inside one of the allowlisted directories, or it's a relative path that resolved somewhere unexpected — use absolute paths.
Symlinks not followed: some versions restrict symlink traversal outside the allowlist for safety; resolve the real path and allowlist that directly if needed.
npx not found in Claude Desktop: GUI apps don't inherit your shell's PATH — use the absolute path to npx or node in the config.
Changes not appearing after config edit: fully restart the client; MCP servers are launched at startup.

Author & links

Author: Model Context Protocol project (Anthropic-maintained)

Repo: github.com/modelcontextprotocol/servers

License: MIT

Related skills

For querying CSV/Parquet files in one of those directories with real SQL, pair this with the DuckDB MCP server. For fetching remote content into the same workflow, see the Fetch MCP server. For repo-hosted files via the GitHub API instead of a local clone, see the GitHub MCP server.

← Back to MCP Servers