wizTree MCP

How it works

wizTreeMCP is a Python MCP server that drives WizTree from an LLM. You can connect it to Claude Code, Cursor, or DeepSeek Harness and you can ask in natural language "what's taking up space on drive C:?", "find all files over 1 GB in Downloads", "how much space do videos take in this folder?", "are there any python orphan dependencies that I can cleanup?".

I find it very useful for wsl, python, docker, npm unused cache files cleanup.

Single file: wiztree_mcp.py. Works on Windows only, because WizTree is a Windows application.

WizTree has no API: it has a command line that exports a CSV of everything it has scanned. The server uses that.

LLM (MCP client) --stdio--> wiztree_mcp.py --CLI--> WizTree64.exe
                                  |                      |
                                  |<----- CSV snapshot ---
                                  |
                        streaming queries on the CSV

A scan runs once and is saved as a CSV snapshot in the cache. All follow-up questions are answered by reading that CSV in streaming: no re-scan of the disk, no loading the entire drive into memory. A snapshot of half a million files takes ~50 MB and answers a query in about a second.

Snapshots are reused automatically: if you scanned C:\ and then ask something about C:\Users\me\Downloads, the server reuses the existing snapshot instead of doing the work again.

Installation

Requires Python 3.10+.

cd wiztree-mcp
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt

The virtual environment has already been created in .venv: if that is enough for you, you are set.

The server finds WizTree64.exe on its own if the wiztree-mcp folder sits inside the WizTree portable folder, or if WizTree is installed in Program Files. Otherwise point it with the WIZTREE_EXE environment variable.

Connecting to Claude Code

One command, no JSON editing — it handles the merge:

claude mcp add wiztree --scope user -- "C:\path\to\wiztree-mcp\.venv\Scripts\python.exe" "C:\path\to\wiztree-mcp\wiztree_mcp.py"

--scope controls where the registration is stored:

Verify:

claude mcp list

Then exit and restart claude: MCP servers connect at session startup, never hot. Inside the session the tools are named mcp__wiztree__wiztree_scan and the like, but you do not need to name them: just ask "what's using space on D:".

If you prefer project scope without the CLI, you can also write a .mcp.json by hand in the folder from which you launch claude, with the same structure shown below for Cursor. On the first session Claude Code asks you to approve it, because a project .mcp.json is not trusted automatically.

Connecting to Cursor

{
  "mcpServers": {
    "wiztree": {
      "command": "C:\\path\\to\\wiztree-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\wiztree-mcp\\wiztree_mcp.py"],
      "env": {
        "WIZTREE_EXE": "C:\\path\\to\\WizTree64.exe"
      }
    }
  }
}

Point to .venv\Scripts\python.exe, not system python: that way you do not need to activate the environment and Cursor always finds the dependencies.

The file cursor-mcp.json already contains the snippet with the correct absolute paths for this installation: open it and copy it.

Or let the script do it — it keeps other servers already configured and makes a backup:

.venv\Scripts\python.exe install_mcp.py

Restart Cursor: in the MCP list you should see wiztree with 16 tools. Agent mode is required; MCP tools are not called in Ask mode.

Connecting to DeepSeek Harness

Here the JSON used by the other two clients does not apply, so copying the Cursor config and changing paths will not work. DeepSeek Harness (dsh) has no mcpServers key: it mounts each MCP server as a plugin instance of @deepseek-ai/dsh-mcp-client in a YAML file. One plugin instance = one MCP server.

The entry to add to the list:

- id: mcp-wiztree
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: wiztree
    transport: stdio
    command: C:\path\to\wiztree-mcp\.venv\Scripts\python.exe
    args:
      - C:\path\to\wiztree-mcp\wiztree_mcp.py
    env:
      WIZTREE_EXE: C:\path\to\WizTree64.exe
    toolCallTimeoutMs: 900000

The file dsh-cordis-patch.yml already has the absolute paths ready.

Where to put it: in the profile's cordis.patch.yml, or in the harness home one ($DSH_HOME, default ~/.dsh). Layers stack in this order — profile bundle, profile cordis.patch.yml, harness home cordis.patch.yml, and finally overlays passed with --patch. Check the effective result with dsh --dump-config.

Three things that matter here:

• toolCallTimeoutMs: 900000. The default is 60000 ms, one minute. Scanning a full drive without administrator privileges takes much longer and the call would be cut off halfway. The other clients do not have such a tight limit.

• Windows paths without double quotes. In YAML, double quotes interpret escape sequences, so "C:\Users\..." fails to parse on \U. Without quotes, or with single quotes, backslashes stay literal.

• Tool names become mcp__wiztree__wiztree_scan and so on, the same convention as Claude Code.

DeepSeek Harness is in developer preview, so this format may change between releases: if something does not match, compare with the official MCP documentation.

Tools

All query tools accept path, refresh, max_age_minutes, admin, filter, filter_exclude, timeout_seconds and scan on their own if they do not find a valid snapshot: the LLM can go straight to wiztree_top_files without calling wiztree_scan first.

Using the GUI and the AI together

You can keep the WizTree window open, click around, and ask questions from chat at the same time. It works, but it is worth knowing how far it goes.

WizTree draws the file list in a TVirtualDrawTree: an owner-drawn control where rows do not exist as text but are painted on the fly. From outside the process they are pixels, not data. The results you see on screen are not readable.

What the window does expose through normal Win32 messages is where it is pointing, and that is enough:

1. WizTree window (pid 58140)
   Title           : [C:\Users\...\wiztree mcp test]  - WizTree
   Loaded target   : C:\Users\...\wiztree mcp test
   Drive selector  : <Select folder...>
   Available       : [C:] OS , [D:] Local Disk , <Select folder...>, ...
   Tabs            : File View, Tree View

So the flow is: you click [D:] in the GUI → ask "what's using space here?" → wiztree_gui_state reads that the window points to D: → the other tools answer about D:. You do not need to type any path.

Two ways to share data with the window open:

• Re-scan (zero friction). The server scans on its own the target it reads from the GUI. It costs the time of one scan.

• CSV handoff (instant). In the GUI do File > Export, then wiztree_import_csv. No re-scan, and if the GUI was running as administrator you carry over the MFT scan. This is the fastest way to work on a full drive.

Both approaches coexist: a command-line export was verified to run in half a second while a WizTree window is open, without disturbing it — the global mutex does not block concurrent instances.

Note: WizTree64.exe path.csv loads the CSV only in headless mode (with /export or /treemapimagefile). Launched without switches it does not open the GUI on that CSV; it falls back to a default drive. In the GUI the CSV is opened from the drive dropdown, <CSV File> entry.

Fast scans: admin

On NTFS volumes WizTree reads the MFT directly, which is why it scans a full drive in seconds. But reading the MFT requires administrator privileges.

• Non-elevated process (the normal case with Cursor): WizTree falls back to a recursive folder scan. On C:\ it can take several minutes; on a single folder it is still fast (~500k files in 5 seconds).

• admin: true: WizTree relaunches elevated and uses the MFT. This triggers the Windows UAC prompt, which must be accepted manually.

If you need this often, launch Cursor as administrator: the server inherits elevation and all scans become immediate with no further prompts. wiztree_info tells you which situation you are in.

Environment variables

Tests

.venv\Scripts\python.exe test_smoke.py

Starts the server over stdio exactly as Cursor does, creates a test tree (with spaces and commas in names) and exercises all 16 tools: 37 checks.

To try it on real data:

.venv\Scripts\python.exe test_manual.py "C:\Users\me\AppData\Local"

Implementation details that may save you time

Things discovered in the field while working with the WizTree 4.32 CLI, not documented anywhere:

• CSV headers are localized. In Italian the first column is called Nome file, not File Name. The first 7 columns are always in the same order, while optional ones (DRIVECAPACITY, CREATEDDATE, MFTRECNO, …) keep a stable ASCII name. The parser relies on position for the first columns and on name for the others.

• No quotes inside arguments. Passing /export="C:\out.csv" from subprocess makes WizTree open an invisible modal error window and the process hangs forever. Values must be passed bare (/export=C:\out.csv) and let Python do the quoting for CreateProcess.

• Files without an extension are exported with a trailing dot: payload becomes payload.. Windows does not allow trailing dots in names, so the parser removes it.

• WizTree can re-read its own CSVs. Passing an exported .csv as the scan path works: that is how treemaps are drawn from a snapshot without touching the disk again.

• Nonexistent path = exit code 0 and no file. There is no error code to check: you must verify that the output file was created.

• There is a global mutex (WizTreeMutex): invocations are serialized with a lock.

• The duplicate finder exists only in the GUI. The binary contains Duplicate Files:, Duplicates only, the DUPSIZE/DUPCOUNT columns, and the INI key dupmethod, but no command-line switch reaches them. wiztree_duplicates therefore does not call WizTree: it groups by size from the snapshot and reads from disk only files that share a size with someone else.

• /exportlimit=N truncates the export to N rows in traversal order, not a global top-N. That is why ranking is done here, in streaming over the CSV, and not by WizTree.

• /sortby values: 0 no order, 1 size, 2 allocated, 3 modification date.

License

MIT. WizTree is software by Antibody Software, distributed under its own license: this project only invokes its command line.