WizTree MCP

WizTree MCP is a local Model Context Protocol server for Windows disk analysis. It wraps WizTree's command-line exports and exposes them as MCP tools for Claude Code, Codex, and other MCP clients.

The server is built for local use: scans are read-only, exported artifacts stay on your machine, and deletion requires a two-step plan before any file is permanently removed.

Features

• Scan a drive or folder and return the largest files/folders.
• Summarize disk usage by extension.
• Export a WizTree treemap PNG.
• Read generated CSV/PNG artifacts through MCP resources.
• Prepare, review, commit, or cancel guarded permanent file deletion plans.

Requirements

• Windows.
• Python 3.11 or newer.
• uv for dependency management.
• WizTree with command-line support. Set WIZTREE_EXE if it is not installed in a standard location.

Install

git clone <repo-url>
cd wiztree-mcp
uv sync

If WizTree is in a custom location:

$env:WIZTREE_EXE = "G:\NTOOLS\WizTree\WizTree64.exe"

Run

uv run wiztree-mcp

The server uses stdio transport. It is normally launched by an MCP client rather than run manually in an interactive terminal.

Claude Code

This repository includes a project-level .mcp.json:

{
  "mcpServers": {
    "wiztree": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "wiztree-mcp"],
      "env": {
        "WIZTREE_DEFAULT_TARGET": "${WIZTREE_DEFAULT_TARGET:-C:}",
        "WIZTREE_TIMEOUT_SEC": "${WIZTREE_TIMEOUT_SEC:-900}"
      }
    }
  }
}

Open Claude Code from the repository root. Claude Code will detect .mcp.json and ask for approval before using the project-scoped MCP server.

You can also add it with the Claude Code CLI:

claude mcp add wiztree --scope project -- uv run wiztree-mcp

Useful environment variables:

| Variable | Default | Description | |---|---|---| | WIZTREE_EXE | Auto-detected | Path or command name for WizTree64.exe / WizTree.exe. | | WIZTREE_DEFAULT_TARGET | C: | Default target for scan tools. | | WIZTREE_ARTIFACT_DIR | %LOCALAPPDATA%\wiztree-mcp\artifacts | Output directory for CSVs, treemap PNGs, and delete plans. | | WIZTREE_TIMEOUT_SEC | 900 | Timeout for each WizTree process. |

Tools

scan_disk

Scan a disk or folder with WizTree and return the largest entries.

Parameters:

• target: Drive or folder to scan. Default: C:.
• admin: Run WizTree with admin mode. Default: false.
• limit: Maximum entries to return. Default: 200.
• filter: Optional WizTree filter.
• exclude: Optional WizTree exclude filter.
• includeFiles: Include files. Default: true.
• includeFolders: Include folders. Default: true.

summarize_extensions

Export WizTree file type data and return usage grouped by extension.

Parameters:

• target: Drive or folder to scan.
• admin: Run WizTree with admin mode.
• limit: Maximum extension rows to return.
• filter: Optional WizTree filter.
• exclude: Optional WizTree exclude filter.

export_treemap

Export a WizTree treemap PNG and return a wiztree-artifact://... resource URI.

Parameters:

• target: Drive or folder to scan.
• admin: Run WizTree with admin mode.
• width: Output width, 100-10000.
• height: Output height, 100-10000.
• showAllocated: Show allocated size.
• showFreeSpace: Include free space.
• gray: Use grayscale output.

prepare_delete

Create a pending delete plan for regular files only. Directories, system roots, symlinks/reparse points, UNC paths, and paths outside allowed roots are rejected.

Parameters:

• paths: File paths to inspect.
• reason: Required cleanup reason.

commit_delete

Commit a pending delete plan. Every file is revalidated by path, size, and modification timestamp before deletion.

cancel_delete

Cancel a pending delete plan.

Resources

Generated artifacts are exposed as MCP resources:

wiztree-artifact://csv/<filename>.csv
wiztree-artifact://filetypes/<filename>.csv
wiztree-artifact://treemap/<filename>.png

Safety Model

Deletion is intentionally conservative:

• Only regular files can be deleted through MCP tools.
• Directories cannot be deleted through prepare_delete.
• Deletion defaults to the current user's home directory and temp locations.
• Sensitive system/application roots are denied, including C:\Windows\System32, C:\Program Files, C:\Program Files (x86), C:\ProgramData, C:\Boot, C:\Recovery, and C:\System Volume Information.
• A plan must be prepared before commit.
• A file is rejected at commit time if it changed after preparation.

Use Windows Disk Cleanup, DISM component cleanup, or the relevant app uninstaller for system caches and installer stores.

Development

uv sync --dev
uv run pytest

Integration tests run only when WIZTREE_EXE points to an available WizTree executable.