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-destructiveimplies--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-writeis passed; they don't appear in tool listings otherwise - Destructive gating — destructive tools (delete, move) are only registered when
--allow-destructiveis passed;--allow-destructiveautomatically enables--allow-write - Binary detection —
read_filescans 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