sand-mcp-fs

MCP Filesystem Server with Sandbox Security

A secure MCP (Model Context Protocol) filesystem server based on cap-std sandbox technology. All file operations are restricted to user-specified allowed directories, preventing unauthorized access to system files.

Features

🔒 Sandbox Security - Based on cap-std capability-based security
📁 8 File Tools - read, write, list, create, move, search, info, list allowed dirs
📏 File Size Limit - Prevent memory exhaustion from large files
🔗 Symlink Support - Correctly handles symbolic links
🚀 CLI Configuration - Easy command-line configuration

Installation

# Clone the repository
git clone https://gitcode.com/lileeei/sand-mcp-fs.git
cd sand-mcp-fs

# Build and install
cargo install --path .

Usage

# Basic usage with default 50MB limit
sand-mcp-fs /path/to/allowed/dir

# Custom file size limit (100MB)
sand-mcp-fs --max-file-size 100MB /path/to/allowed/dir

# Multiple allowed directories
sand-mcp-fs --max-file-size 1GB /dir1 /dir2 /dir3

CLI Options

Option	Default	Description
`--max-file-size`	50MB	Maximum file size for read operations
`<directories>...`	(required)	Allowed directories

MCP Tools

Tool	Description
`read_file`	Read file contents (supports head/tail)
`write_file`	Write content to a file
`list_directory`	List directory contents
`create_directory`	Create a new directory
`get_file_info`	Get file/directory metadata
`move_file`	Move/rename files
`search_files`	Search files by glob pattern
`list_allowed_directories_tool`	List all allowed directories

Security

Path Canonicalization - All paths are resolved to absolute form
Sandbox Boundary - Operations restricted to allowed directories
Capability-based Access - Uses cap-std for all file operations
File Size Limit - Prevents memory exhaustion attacks

Configuration for OpenCode

Add to ~/.config/opencode/opencode.json:

{
    "mcp": {
        "sand-mcp-fs": {
            "type": "local",
            "command": [
                "sand-mcp-fs",
                "--max-file-size",
                "50MB",
                "/home/user"
            ],
            "enabled": true
        }
    }
}

File Size Format

Supported suffixes:

KB - Kilobytes (1024 bytes)
MB - Megabytes (1024 * 1024 bytes)
GB - Gigabytes (1024 * 1024 * 1024 bytes)

Examples:

sand-mcp-fs --max-file-size 100KB /data
sand-mcp-fs --max-file-size 500MB /data
sand-mcp-fs --max-file-size 2GB /data

License

Apache-2.0

sand-mcp-fs 0.1.0