How to Set Up and Use the Filesystem MCP Server — Complete Guide

The Filesystem MCP server gives your AI assistant scoped read and write access to directories you explicitly approve. With 11 tools and ~5,665 tokens of overhead, it is one of the lightest MCP servers available -- and the only one built around a directory allowlist security model.

TL;DR: Pass allowed directories as arguments when starting the server. The assistant can read, write, search, and manage files only within those directories. No API keys needed. Most useful for clients without built-in file access (Claude Desktop) or when you need cross-project file access.

Filesystem MCP | npm | Tools: 11 | ~5,665 tokens

graph TD
    A[Configure allowed directories] --> B[Start MCP server]
    B --> C{File operation request}
    C -->|Inside allowlist| D[Execute operation]
    C -->|Outside allowlist| E[Access denied]

What the Server Exposes

Reading: read_file, read_multiple_files, get_file_info, list_directory

Writing: write_file, edit_file (search-and-replace with diff output)

Searching: search_files (recursive pattern matching), list_allowed_directories

Management: create_directory, move_file, directory_tree

The Directory Allowlist

The defining feature. When you start the server, you pass directory paths as arguments. These are the only directories accessible. No escape, no traversal, no symlink bypass.

"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects/my-app", "/Users/me/data"]

This matters because:

• Without an allowlist, "find all config files" could scan your entire filesystem
• Write access is constrained to directories you control
• Multi-project isolation prevents accidental cross-project modifications
• Shareable configs ensure team members have appropriate scope

Setup

No API keys. No environment variables. Just directory paths.

Claude Code

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

Multiple directories:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/projects/my-app",
        "/Users/me/shared-configs",
        "/Users/me/data/datasets"
      ]
    }
  }
}

See the full Claude Code setup guide.

Cursor

Create .cursor/mcp.json:

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

See the Cursor setup guide.

VS Code (Copilot)

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/Users/me/projects/my-app"
        ]
      }
    }
  }
}

Windows paths

"args": [
  "-y",
  "@modelcontextprotocol/server-filesystem",
  "C:\\Users\\me\\projects\\my-app"
]

Workflows

Analyze project structure

"Show the directory tree, read package.json and tsconfig.json, then find TypeScript files in src/ that are not imported by any other file."

• directory_tree for full structure
• read_multiple_files for config files
• search_files + read_file to trace import chains and find orphans

Create a new module with proper file structure

"Create src/modules/notifications/ with types.ts, service.ts, index.ts, and service.test.ts. Use patterns from the existing src/modules/auth/ module."

• Reads the existing module to learn your conventions
• Uses create_directory + write_file to build the new module
• Generated code follows your actual codebase patterns, not generic templates

Search and replace across files

"Find all files importing from '@utils/helpers' and update them to import from '@lib/helpers'."

• search_files locates matches
• edit_file performs replacements with diff output for verification

Batch file operations

"Find all .test.ts files next to their source files. Move each into a tests subdirectory."

• search_files + list_directory to identify test files
• create_directory + move_file to reorganize

Inspect file metadata

"Check file sizes and last modified dates in dist/. Any files larger than 1MB?"

• list_directory + get_file_info for sizes and timestamps
• Identifies large bundles and stale build artifacts

Token Impact

At ~5,665 tokens (<3% of 200K), this is one of the lightest servers you can run. Compare to Playwright MCP (~10,300) or Supabase MCP (~12,875). Easy addition to any stack without token budget concerns.

When You Need It vs When You Don't

You probably don't need it if:

• You use Claude Code -- built-in file reading, writing, and searching covers the same ground
• You use Cursor or Windsurf -- these editors give the AI direct workspace file access

You do need it if:

• Access to files outside your project -- shared configs, data directories, other projects
• Explicit access control -- the allowlist model provides fine-grained scoping
• Claude Desktop or chat-based clients -- no workspace concept, so this is the primary file access method
• AI agents or automation pipelines -- structured, scoped file access via MCP protocol
• Cross-project work -- spanning multiple directories that your editor does not know about

Common Gotchas

Path resolution

All paths must be absolute. Relative paths like ./src/index.ts may not resolve correctly.

Symlinks

Followed within allowed directories. Symlinks pointing outside the allowlist fail -- a security feature.

Large files

read_file loads entire contents into the context window. Check size with get_file_info first for multi-megabyte files.

Binary files

Designed for text files. Binary files (images, binaries, archives) return garbled content.

Write safety

No undo mechanism. Always ensure your directory is under version control before granting write access. Revert with git checkout or git restore.

Concurrent access

No file locking. If you edit a file in your editor while the assistant modifies it via MCP, conflicts can occur. Save editor changes first.

For more help, see the MCP troubleshooting guide and how to secure your MCP server setup.

Allowlist Configurations

Solo developer, single project:

"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects/my-app"]

Monorepo:

"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects/monorepo"]

Data science with separate data:

"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects/ml-project", "/Users/me/datasets"]

Multiple related projects:

"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects/frontend", "/Users/me/projects/backend", "/Users/me/projects/shared-types"]

Resist the temptation to pass a broad parent directory "for convenience." The narrower the scope, the safer the setup.

Pairing with Other Servers

• GitHub MCP: Read local files for context, then push changes to a remote repository
• Supabase MCP: Generate types from the database, write them to your project files
• Playwright MCP: Modify source files, then verify the changes render correctly in a browser

This server is particularly useful for data scientists and AI/ML engineers who work with files across multiple directories.

Getting Started

Add the config with your allowed directories, reload your editor, and test with: "Show me the directory tree of my project." The server delivers immediate value with zero configuration beyond the directory paths.

For stacks that include Filesystem MCP, browse the curated configurations.