unix-disk-mcp

AI-assisted disk cleanup for Unix systems (macOS and Linux). Let an LLM explore your filesystem, identify unused files, and suggest what to delete. You stay in control — the AI can only suggest and stage items, never delete them.

Why?

Traditional disk cleaners use fixed rules. This tool lets AI reason about your actual usage:

• "3 Node.js installations via different methods"
• "40GB VM untouched for 14 months"
• "Docker images for deleted projects"
• "Homebrew packages nothing depends on"

Security

The AI cannot delete files. Ever. This is architectural:

What AI can do:

• Explore filesystem
• Suggest items to delete
• Stage items for deletion

What AI cannot do:

• Execute deletion
• Run delete script

You run unix-disk-mcp delete manually to review and confirm.

Install

npm install -g unix-disk-mcp
unix-disk-mcp setup

The setup wizard configures everything. Or manually:

1. Add to MCP client config:

VS Code: ~/Library/Application Support/Code/User/mcp.json (macOS) or ~/.config/Code/User/mcp.json (Linux)

{
  "servers": {
    "unix-disk-mcp": {
      "type": "stdio",
      "command": "unix-disk-mcp"
    }
  }
}

Cursor: ~/.cursor/mcp.json

{
  "mcpServers": {
    "unix-disk-mcp": {
      "command": "unix-disk-mcp",
      "args": []
    }
  }
}

Claude: ~/.claude.json

{
  "servers": {
    "unix-disk-mcp": {
      "type": "stdio",
      "command": "unix-disk-mcp"
    }
  }
}

2. Configure protected paths:

Run unix-disk-mcp config to see config location, then edit:

{
  "protected_paths": ["/System", "/Library", "~/.ssh", "~/.gnupg"]
}

Usage

1. Ask AI to explore:

• "What's using disk space?"
• "Find large files I don't need"
• "Check for old Docker images"

2. AI stages items:

Staged for deletion:
1. ~/.cache/pip (2.3 GB)
2. ~/Downloads/old-installer.dmg (1.5 GB)
Total: 3.8 GB

3. You delete manually:

unix-disk-mcp delete
# Reviews staged items, requires typing HUMAN, then y/N confirmation

Tools Available to AI

Exploration:

• list_directory - Browse folders
• get_disk_usage - Disk space overview
• find_large_items - Find big files/folders (supports progressive depth exploration)
• get_item_info - Details on specific paths
• search_files - Find files/directories by name pattern

Discovery:

• list_applications - Installed apps with last-opened dates (macOS); app list only on Linux
• list_packages - Installed packages (Homebrew, apt, dnf, yum, pacman)
• list_docker - Docker images, containers, volumes

Staging:

• stage_for_deletion - Mark for deletion
• unstage - Remove from staging
• get_staged - View staged items

Platform Support

macOS:

• Trash via AppleScript
• Accurate APFS disk usage (diskutil)
• App discovery via Spotlight with last-opened dates
• Homebrew package listing

Linux:

• Trash via gio/trash-cli/freedesktop spec
• Disk usage via df
• App discovery via .desktop files (no last-opened dates)
• System package manager support (apt, dnf, yum, pacman) + Homebrew if installed

Safety Features

1. AI cannot delete (architecturally separated)
2. Terminal check (blocks piped input)
3. Human verification required (type "HUMAN")
4. Protected paths cannot be staged
5. Items go to Trash (recoverable)
6. Deletion requires manual terminal command
7. Confirmation prompt before deletion
8. Deletion history logged

Commands

unix-disk-mcp          # Start MCP server (default)
unix-disk-mcp setup    # Setup wizard
unix-disk-mcp delete   # Delete staged items (manual only)
unix-disk-mcp config   # Show config location
unix-disk-mcp help     # Show help

Config & Data

• Config: ~/.config/unix-disk-mcp/config.json
• Staged items: ~/.local/share/unix-disk-mcp/staged.json
• History: ~/.local/share/unix-disk-mcp/history.json

License

GPL-3.0-or-later