MCP server for filesystem access: how to give Claude safe file operations

The problem with giving Claude shell access

The obvious way to let Claude manage your files is to give it a bash tool. Most MCP tutorials take this route. It works — until it doesn’t.

Raw shell access means Claude can run rm -rf, overwrite files silently, and scatter things across your filesystem with no record of what happened. There is no undo. If the model misunderstands your intent or you approve the wrong plan, the damage is permanent.

A purpose-built filesystem MCP server solves this by putting a safety layer between the model and your disk. The model can still scan, organize, deduplicate, and clean — but every operation is journaled, system directories are blocked, and a single command reverses anything.

What a filesystem MCP server does differently

Instead of exposing bash, a filesystem MCP server exposes a set of typed tools: scan, organize, plan, apply, rollback. The model can only do what those tools allow. The tools themselves enforce constraints the model can’t bypass:

• Path jailing. Symlinks are resolved before validation. System directories (/System, C:\Windows, /etc, /proc) are on a blocklist and cannot be touched regardless of what the model is asked to do.
• Plan-then-apply gate. Scanning and planning are read-only. Only the explicit apply call mutates disk — and only after the user has reviewed the plan.
• Write-ahead journal. Every move is recorded before it happens. A single rollback call reverses the entire session, even if the process crashed mid-apply.
• No file contents egress. The server sends only metadata to the model — names, sizes, paths, extensions. File contents never leave the machine.

Setting it up in Claude Desktop

The FileMayor MCP server is available as an npm package. You don’t need to install it globally — npx handles it on demand.

1. Verify the server before wiring it in

Run the audit flag first. It prints a structured trust report and exits without starting an MCP session:

npx -y @filemayor/mcp --audit

The output tells you the transport type (stdio — no network listener), what outbound calls the server can make (one optional Gemini call for AI planning, gated by an env var), and the complete list of tools with their destructive flags. Diff it after upgrades to catch changes.

2. Add one entry to claude_desktop_config.json

On macOS this file is at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows: %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "filemayor": {
      "command": "npx",
      "args": ["-y", "@filemayor/mcp"]
    }
  }
}

If you want AI-powered planning (the filemayor_plan tool), add a Gemini API key — it’s free up to 1,500 requests/day on Google’s free tier:

{
  "mcpServers": {
    "filemayor": {
      "command": "npx",
      "args": ["-y", "@filemayor/mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

3. Restart Claude Desktop

After restarting, open a new conversation and look for the hammer icon (🔧). You should see 14 FileMayor tools available. Ask Claude to diagnose a folder:

Diagnose my Downloads folder and tell me what's taking up the most space.

The tools Claude gets

The server exposes 14 tools. The key ones for filesystem management:

• filemayor_scan — recursive file inventory with sizes and categories
• filemayor_explain — health score (0–100), identified issues, savings estimate
• filemayor_plan — AI-generated reorganisation plan from a natural-language prompt (requires GEMINI_API_KEY)
• filemayor_apply — executes the most recent plan; writes the journal
• filemayor_rollback — reverses the most recent applied plan
• filemayor_organize — deterministic auto-organize by extension (no API key required)
• filemayor_duplicates — hash-based duplicate detection
• filemayor_dedupe — find and remove duplicates (destructive, flagged)
• filemayor_clean — find junk files (.DS_Store, Thumbs.db, temp files)

Every applied plan can be reversed. The journal survives crashes.

The same server works in Cursor and Zed

Any MCP client that speaks stdio works. In Cursor, add the same configuration to your MCP settings. In Zed, add it to ~/.config/zed/settings.json:

{
  "context_servers": {
    "filemayor": {
      "command": {
        "path": "npx",
        "args": ["-y", "@filemayor/mcp"]
      }
    }
  }
}

What this does not replace

A filesystem MCP server is not a full-featured file manager. It doesn’t replace Finder or Explorer for manual browsing, drag-and-drop, or app-specific operations like ejecting drives. It’s specifically for bulk operations — the quarterly cleanup, the project archiving, the deduplication run you keep putting off — where AI planning and undo matter more than a visual interface.

For the details on the full security model, see the MCP server documentation.