Filesystem MCP Server

The Filesystem MCP Server is Anthropic’s official implementation for giving AI agents secure, controlled access to your local files. It’s the most commonly deployed MCP server, and for good reason: nearly every practical AI workflow eventually needs to read or write a file.

What the Filesystem MCP Server Does

The server exposes 13 tools across two categories: read-only operations (9 tools) and write operations (4 tools). Read operations include retrieving file contents, listing directories, searching with glob patterns, reading image files as base64, and inspecting file metadata. Write operations cover creating and overwriting files, making selective edits, creating directories, and moving files.

The security model is whitelist-based. You specify which directories the server is allowed to access when you start it — it cannot touch anything outside those paths. All file operations also require explicit approval from the user via the Claude Desktop UI before execution. Symlinks are validated to prevent path traversal outside allowed directories.

This makes it practical to point the server at your project directory without worrying about it touching system files.

Installation

Prerequisites: Node.js installed on your system. The package targets Node 22+ types but runs on Node 18+ in practice — no minimum is declared in package.json.

The server is published as @modelcontextprotocol/server-filesystem on npm. No global installation needed — the npx method is recommended.

Claude Desktop configuration (claude_desktop_config.json):

macOS path: ~/Library/Application Support/Claude/claude_desktop_config.json Windows path: %APPDATA%\Claude\claude_desktop_config.json

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

You can specify multiple directories as additional arguments. All paths must be absolute.

Docker (read-only mode):

docker run -i --rm \
  -v /path/to/projects:/projects:ro \
  mcp/filesystem /projects

The :ro flag mounts the directory read-only, giving the server no write access.

Available Tools

Tool	Type	What It Does
read_text_file	Read	File contents as text (1MB limit)
read_media_file	Read	Images/audio as base64 with MIME type
read_multiple_files	Read	Batch read, doesn’t stop on failures
list_directory	Read	Directory contents with file/dir labels
list_directory_with_sizes	Read	Directory listing with file sizes
directory_tree	Read	Recursive JSON tree, supports exclusions
search_files	Read	Glob pattern search with exclusions
get_file_info	Read	Size, timestamps, permissions, type
list_allowed_directories	Read	Which directories this server can access
write_file	Write	Create or overwrite a file
edit_file	Write	Pattern-match edits with dry-run preview
create_directory	Write	Create directory (with parent creation)
move_file	Write	Rename or relocate files/directories

Limitations

• 1MB file read limit per operation. Large files need chunking.
• Absolute paths only. Relative paths resolve against the server’s working directory, not your project root — this will surprise you if you’re not careful.
• UTF-8 assumption. Binary file writing isn’t supported; you can read binary files as base64 but not write them.
• Move fails if destination exists. No overwrite option on move — you’d need to delete first.
• No file watching. The server is request-driven only; it doesn’t emit events when files change.
• No transaction support. Multiple write operations are independent — no rollback if one fails mid-sequence.

Example Workflow

User: Refactor all the TypeScript files in /projects/myapp/src to use
      named exports instead of default exports.

Claude: [uses list_directory to enumerate .ts files]
        [uses read_multiple_files to load them all]
        [uses edit_file on each file with dry-run first]
        [presents diff preview]
        [awaits user approval]
        [applies changes]

This workflow — enumerate, read, edit with preview, approve, execute — is the standard pattern for AI-assisted refactoring.

Alternatives

If you need Git-aware file operations, use the GitHub MCP Server instead — it understands branches, diffs, and PRs, not just raw files.

For teams that need cross-session file persistence or multi-machine access, look at cloud storage MCP servers (Fast.io MCP is one option). The Filesystem server is local-only.

The MCP ecosystem also has community filesystem servers with additional features — notably cyanheads/filesystem-mcp-server for advanced search/replace, and a Go implementation (mark3labs/mcp-filesystem-server) if you want a lower-overhead binary. The Anthropic official server is the right default: most stable, best documented, guaranteed to stay current with the MCP spec.

Our Take

The Filesystem MCP Server does what it says, securely, with good tool coverage. The whitelist security model and user-approval requirement make it practical to actually deploy. The 1MB file limit and lack of file watching are the main gaps — both are real constraints if you’re building complex pipelines on top of it, but reasonable for interactive use.

Best for: Any local development workflow where you want Claude to read or edit files in your project.

Skip if: You’re working primarily with remote repositories (use GitHub MCP Server), or need to stream large files.

Rating: 9.0/10