ironbeard-mcp-filesystem

A secure filesystem MCP server written in Rust. Provides 13 tools for file operations with strict path sandboxing and tiered permission gating.

Features

• 7 read-only tools — always available
• 3 write tools — gated behind --allow-write
• 3 destructive tools — gated behind --allow-destructive
• Path sandboxing — only operates within explicitly allowed directories
• Symlink escape prevention — symlinks resolving outside allowed dirs are blocked
• Binary file detection — null-byte scanning in first 8KB
• Large file handling — configurable size limits with offset/limit support
• Large directory safety — results truncated at 1000 entries

Installation

git clone <repo-url>
cd ironbeard-mcp-filesystem
cargo build --release

The binary will be at target/release/ironbeard-mcp-filesystem (or .exe on Windows).

Usage

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/ironbeard-mcp-filesystem",
      "args": ["/path/to/allowed/dir1", "/path/to/allowed/dir2"]
    }
  }
}

With Write Access

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/ironbeard-mcp-filesystem",
      "args": ["--allow-write", "/path/to/project"]
    }
  }
}

With Destructive Access

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/ironbeard-mcp-filesystem",
      "args": ["--allow-destructive", "/path/to/project"]
    }
  }
}

--allow-destructive implies --allow-write, so you don't need to pass both.

CLI Arguments

ironbeard-mcp-filesystem [OPTIONS] <DIRECTORIES>...

Tools

Read-Only Tools (always available)

Write Tools (require --allow-write)

Destructive Tools (require --allow-destructive)

Configuration

Security Model

All file operations are sandboxed to explicitly allowed directories:

• Path validation — every path is canonicalized and checked against the allowlist before any I/O
• Symlink resolution — symlinks are resolved to their real target; escapes outside allowed dirs are blocked
• Traversal prevention — ../ path components are neutralized via canonicalization
• Write gating — write tools are only registered when --allow-write is passed; they don't appear in tool listings otherwise
• Destructive gating — destructive tools (delete, move) are only registered when --allow-destructive is passed; --allow-destructive automatically enables --allow-write
• Binary detection — read_file scans the first 8KB for null bytes and rejects binary files
• Size limits — large files are rejected unless offset/limit narrows the read

Development

# Run tests
cargo test

# Format check
cargo fmt --check

# Lint
cargo clippy -- -D warnings

# Release build
cargo build --release

License

MIT