filesystemMCP

Secure filesystem operations via Model Context Protocol — works across all three Claude clients.

MCP 2025-11-25 FastMCP OAuth 2.1 15 tools Python 3.11+

Get started View on GitHub

Why filesystemMCP

Built for safety. Built for Claude.

Every operation passes through a five-tier path classification engine before touching disk.

🔒

Five-tier path security

BLOCKED, READ-ONLY, SENSITIVE, CONDITIONAL, and TRUSTED tiers control exactly what Claude can read, write, or delete — with mandatory backups on sensitive paths.

⚡

Atomic writes with rollback

All writes use temp-file + rename for crash safety. SHA-256 checksums on every write. Up to 10 timestamped backup versions per file — one call to restore any of them.

💻

All three Claude clients

Works natively with claude.ai (Chrome extension + Native Messaging), claude-desktop (plugin config), and claude-code (MCP server registration).

🔧

HTTP mode with OAuth 2.1

Run as a remote streamable-HTTP MCP server with PKCE-compliant OAuth 2.1. Auto-approving for personal use. Expose via Tailscale or any reverse proxy.

Security

Path tier policy

All paths are resolved (symlinks followed) before classification. Symlinks targeting blocked paths are rejected.

Tier	Read	Write	Delete	Backup on write	Example paths
BLOCKED	✕	✕	✕	—	/proc /sys /dev /run/secrets
READ-ONLY	✓	✕	✕	—	Configured read-only mounts
SENSITIVE	✓	✓	✓	Required	/etc /usr /root
CONDITIONAL	✓	✓	✓	Required	~/.config ~/.ssh
TRUSTED	✓	✓	✓	None	/home/user/* (configured)

Additional hardening: symlink bypass prevention · exclusive file locks · binary detection · full audit logging on every operation · freedesktop Trash (recoverable delete by default)

Reference

15 MCP tools

All tools are registered with FastMCP annotations marking read-only and destructive hints.

Tool	Type	Description
`read_file`	read	Read a file — optional line range, head/tail, binary detection (returns base64 with flag)
`read_multiple_files`	read	Batch read — returns JSON dict keyed by path; per-path errors don't abort the batch
`list_directory`	read	Recursive listing with depth 1–4 and glob / 'files' / 'dirs' filter
`file_info`	read	JSON metadata: path, type, binary flag, size, mode, mtime, tier classification
`file_exists`	read	Four-state check: exists\|file\|N, exists\|dir, not_found, blocked, symlink_blocked
`list_backups`	read	List all .bak.YYYYMMDD_HHMMSS backup versions for a file, newest first
`list_allowed_directories`	read	Print the full active five-tier path classification policy
`write_file`	destructive	Full atomic overwrite with SHA-256 verification. Requires explicit_intent=true
`edit_file`	destructive	Surgical patch (search+replace) or full overwrite with exclusive lock. Requires explicit_intent=true
`delete_file`	destructive	Trash (recoverable, default) or permanent unlink with permanent=true
`rollback_file`	write	Restore from a timestamped backup. version=0 = most recent. Requires explicit_intent=true
`move_file`	write	Move or rename — both paths are tier-checked
`copy_file`	write	Copy preserving metadata — both paths are tier-checked
`make_directory`	write	Create a directory and all missing parents (mkdir -p)
`sudo_exec`	destructive	Execute a shell command with sudo. confirmed=false (default) shows preview only
`check_syntax`	read	Validate code syntax without executing. Supports bash, python3, javascript, typescript, go

Getting started

Install in 60 seconds

Choose your Claude client below. The server works identically across all three.

claude-code

claude-desktop

claude.ai web

1Clone & install

Clone the repo and run the idempotent installer.

git clone https://github.com/DitherZ/filesystemMCP ~/MCP/filesystemMCP
cd ~/MCP/filesystemMCP
./install.sh

2Register the MCP server

claude-code reads MCP servers from ~/.config/claude-code/mcp-servers.json

{
  "filesystemMCP": {
    "command": "/usr/bin/node",
    "args": ["/home/YOUR_USER/MCP/filesystemMCP/server/index.js"]
  }
}

3Verify

claude mcp list
# filesystemMCP should appear

claude mcp get filesystemMCP
# Shows all 15 registered tools

1Clone & install

git clone https://github.com/DitherZ/filesystemMCP ~/MCP/filesystemMCP
./install.sh

2Add to claude_desktop_config.json

Edit ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "filesystemMCP": {
      "command": "/usr/bin/node",
      "args": ["/home/YOUR_USER/MCP/filesystemMCP/server/index.js"]
    }
  }
}

3Restart claude-desktop

Fully quit from the system tray — the window close button does not restart the server process.

1Install the Chrome extension

The extension bridges claude.ai to the local MCP server via Chrome's Native Messaging API.

mkdir -p ~/.config/Claude/"Claude Extensions"
cp -r ~/MCP/filesystemMCP/extension       ~/.config/Claude/"Claude Extensions"/ant.dir.ant.blackflame.filesystemMCP

Then open chrome://extensions, enable Developer mode, click Load unpacked, and select the directory above.

2Install the Native Messaging host

mkdir -p ~/.config/google-chrome/NativeMessagingHosts

Write ant.blackflame.filesystemmcp.json to that directory with the path to your Node.js binary and the server index.js.

3Verify

Navigate to claude.ai — the filesystemMCP icon should appear in Claude's connector sidebar.