wiztree-mcp: Instructions file for Codex

wiztree-mcp

WizTree-based disk analysis MCP server. Scan drives, query disk usage, search paths, compare scans, and visualize file system data — all from Claude Code.

Quick Start

pip install wiztree-mcp
# WizTree64.exe required on Windows — install from https://diskanalyzer.com/

Register in .mcp.json:

{
  "mcpServers": {
    "wiztree": {
      "type": "stdio",
      "command": ".venv\\Scripts\\python",
      "args": ["-m", "wiztree_mcp"]
    }
  }
}

Architecture

src/wiztree_mcp/
├── __init__.py
├── __main__.py       # Entry point: from server import main; main()
├── server.py         # FastMCP instance, lifespan, tool registration
├── database.py       # SQLite CRUD (scans + entries tables)
├── models.py         # Dataclasses (Scan, Entry, ScanType, EntryType)
├── csv_importer.py   # CSV parser → bulk INSERT into SQLite
├── wiztree_cli.py    # WizTree64.exe discovery & invocation
└── tools/
    ├── scan.py       # scan_disk — primary data ingestion
    ├── query.py      # disk_summary, top_entries, search_paths, drill_down
    ├── analysis.py   # file_type_summary, large_old_files
    ├── compare.py    # compare_scans — SQL FULL OUTER JOIN
    └── manage.py     # list_scans, get_treemap, cleanup_scans

Tools (11 total)

Data Ingestion

• scan_disk(target, label?, max_depth?, export_folders?, export_files?, treemap?, timeout?) — Scan with WizTree, import CSV into SQLite

Query

• disk_summary(scan_id, top_n?) — Drive info + capacity + top files/folders
• top_entries(scan_id, kind?, limit?, offset?) — Largest files/folders
• search_paths(scan_id, query, kind?, limit?) — Keyword search
• drill_down(scan_id, folder_path, limit?, offset?) — Browse folder contents
• file_type_summary(scan_id, limit?) — Disk usage by extension
• large_old_files(scan_id, older_than_days?, min_size_mb?, limit?) — Cleanup candidates

Comparison

• compare_scans(scan_id_before, scan_id_after, limit?) — SQL JOIN diff

Management

• list_scans() — Available scans
• get_treemap(scan_id) — PNG treemap image
• cleanup_scans(keep_latest?) — Remove old scans