wizTree MCP

工作原理

wizTreeMCP 是一个 Python MCP 服务器，用于从 LLM 驱动 WizTree。 你可以将其连接到 Claude Code、Cursor 或 DeepSeek Harness，然后用自然语言提问： "C 盘上什么占用了空间？"、"在 Downloads 中查找所有超过 1 GB 的文件"、 "这个文件夹中视频占用了多少空间？"、"有没有可以清理的 Python 孤儿依赖？"。

我发现它对清理 wsl、python、docker、npm 的未使用缓存文件非常有用。

单文件：wiztree_mcp.py。仅适用于 Windows，因为 WizTree 是 Windows 应用程序。

WizTree 没有 API：它有一个命令行，可以导出它扫描到的所有内容的 CSV。 服务器使用该功能。

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

一次扫描 只执行一次，并作为 CSV 快照 保存在缓存中。 所有后续问题都通过流式读取该 CSV 来回答：无需 重新扫描磁盘，也无需将整个驱动器加载到内存中。包含五十万个文件的快照 大约占用 ~50 MB，回答一个查询大约需要一秒钟。

快照会自动复用：如果你扫描了 C:\，然后询问 关于 C:\Users\me\Downloads 的内容，服务器会复用现有的快照，而不是 重新执行扫描。

安装

需要 Python 3.10+。

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

虚拟环境已在 .venv 中创建：如果这对你来说足够了，那就没问题了。

如果 wiztree-mcp 文件夹位于 WizTree 便携版文件夹内，或者 WizTree 安装在 Program Files 中，服务器会自动找到 WizTree64.exe。否则，请通过 WIZTREE_EXE 环境变量指定其位置。

连接到 Claude Code

一条命令，无需编辑 JSON——它会处理合并：

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

--scope 控制注册信息的存储位置：

验证：

claude mcp list

然后 退出并重启 claude：MCP 服务器在会话启动时连接，绝不会热连接。 在会话中，工具名称类似于 mcp__wiztree__wiztree_scan，但你无需 指定它们：只需问 "D 盘上什么占用了空间？"。

如果你希望使用项目作用域而不使用 CLI，你也可以在启动 claude 的 文件夹中手动编写 .mcp.json，其结构与下面为 Cursor 展示的结构相同。在第一次会话中，Claude Code 会要求你批准它，因为项目 .mcp.json 不会被自动信任。

连接到 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"
      }
    }
  }
}

指向 .venv\Scripts\python.exe，而不是系统 python：这样你无需激活 环境，Cursor 也总能找到依赖项。

文件 cursor-mcp.json 已包含带有正确 绝对路径的片段：打开并复制它。

或者让脚本来做——它会保留已配置的其他服务器并创建备份：

.venv\Scripts\python.exe install_mcp.py

重启 Cursor：在 MCP 列表中你应该会看到 wiztree 及其 16 个工具。Agent 模式是必需的； MCP 工具在 Ask 模式下不会被调用。

连接到 DeepSeek Harness

这里，其他两个客户端使用的 JSON 不适用，因此复制 Cursor 配置 并更改路径是行不通的。DeepSeek Harness（dsh）没有 mcpServers 键：它将每个 MCP 服务器挂载为 YAML 文件中 @deepseek-ai/dsh-mcp-client 的 插件实例。 一个插件实例 = 一个 MCP 服务器。

要添加到列表中的条目：

- 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

文件 dsh-cordis-patch.yml 已准备好绝对路径。

放置位置：在配置文件的 cordis.patch.yml 中，或在 harness 主目录中 （$DSH_HOME，默认为 ~/.dsh）。层按以下顺序堆叠——配置文件包、 配置文件 cordis.patch.yml、harness 主目录 cordis.patch.yml，最后是通过 --patch 传递的覆盖层。使用 dsh --dump-config 检查有效结果。

这里有三件重要的事情：

• toolCallTimeoutMs: 900000。 默认值为 60000 毫秒，即一分钟。在没有管理员权限的情况下扫描整个驱动器 需要更长的时间，调用会在中途被 切断。其他客户端没有如此严格的限制。

• 不带双引号的 Windows 路径。 在 YAML 中，双引号会解释转义序列，因此 "C:\Users\..." 会在 \U 处解析失败。不带引号，或使用 单引号，反斜杠会保持字面意义。

• 工具名称 变为 mcp__wiztree__wiztree_scan 等，与 Claude Code 的约定相同。

DeepSeek Harness 处于开发者预览阶段，因此此格式可能在不同版本之间发生变化： 如果某些内容不匹配，请与 官方 MCP 文档 进行比较。

工具

所有查询工具都接受 path、refresh、max_age_minutes、admin、filter、 filter_exclude、timeout_seconds，如果找不到有效快照，它们会自行扫描： LLM 可以直接调用 wiztree_top_files，而无需先调用 wiztree_scan。

同时使用 GUI 和 AI

你可以保持 WizTree 窗口打开，点击浏览，同时 从聊天中提问。这可行，但值得了解它能做到什么程度。

WizTree 在 TVirtualDrawTree 中绘制文件列表：这是一个 所有者绘制 控件，其中 行不是以文本形式存在，而是即时绘制的。从进程外部来看，它们是 像素，而不是数据。你在屏幕上看到的结果是不可读取的。

窗口通过正常的 Win32 消息暴露的是 它指向的位置，这 就足够了：

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

因此流程是：你在 GUI 中点击 [D:] → 问 "这里什么占用了空间？" → wiztree_gui_state 读取窗口指向 D: → 其他工具回答关于 D: 的问题。 你无需输入任何路径。

在窗口打开时共享数据的两种方式：

• 重新扫描（零摩擦）。 服务器自行扫描它从 GUI 读取的目标。 代价是一次扫描的时间。

• CSV 交接（即时）。 在 GUI 中执行 File > Export，然后执行 wiztree_import_csv。 无需重新扫描，如果 GUI 以管理员身份运行，你还会继承 MFT 扫描。这是在完整驱动器上工作的最快方式。

两种方法共存：已验证命令行导出在 WizTree 窗口打开时 半秒内即可运行，且不会干扰它——全局互斥锁不会阻塞 并发实例。

注意：WizTree64.exe path.csv 仅在无头模式下加载 CSV（使用 /export 或 /treemapimagefile）。不带开关启动时，它不会在该 CSV 上打开 GUI；而是回退 到默认驱动器。在 GUI 中，从驱动器下拉列表的 <CSV File> 条目打开 CSV。

快速扫描：admin

在 NTFS 卷上，WizTree 直接读取 MFT，这就是它能在几秒钟内扫描整个驱动器的原因。但读取 MFT 需要管理员权限。

• 非提升进程（Cursor 的常规情况）：WizTree 回退到递归文件夹扫描。在 C:\ 上可能需要几分钟；在单个文件夹上仍然很快（约 5 秒 50 万个文件）。

• admin: true：WizTree 以提升权限重新启动并使用 MFT。这会触发 Windows UAC 提示，必须手动接受。

如果您经常需要这样做，请以管理员身份启动 Cursor：服务器会继承提升权限，所有扫描都会立即完成，无需进一步提示。wiztree_info 会告诉您当前处于哪种情况。

环境变量

测试

.venv\Scripts\python.exe test_smoke.py

通过 stdio 以与 Cursor 完全相同的方式启动服务器，创建一个测试树（名称中包含空格和逗号），并执行所有 16 个工具：37 项检查。

要在真实数据上试用：

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

可能节省您时间的实现细节

在使用 WizTree 4.32 CLI 时现场发现的问题，未在任何文档中说明：

• CSV 表头已本地化。 在意大利语中，第一列称为 Nome file，而不是 File Name。前 7 列始终按相同顺序排列，而可选列（DRIVECAPACITY、CREATEDDATE、MFTRECNO 等）则保持稳定的 ASCII 名称。解析器对前几列依赖位置，对其他列依赖名称。

• 参数内不能有引号。 从 subprocess 传递 /export="C:\out.csv" 会导致 WizTree 打开一个不可见的模态错误窗口，并且进程会永远挂起。值必须裸传（/export=C:\out.csv），并让 Python 为 CreateProcess 处理引号。

• 没有扩展名的文件导出时会带一个尾随点：payload 变成 payload.。Windows 不允许名称中出现尾随点，因此解析器会将其删除。

• WizTree 可以重新读取自己的 CSV。 将导出的 .csv 作为扫描路径传递是可行的：这就是在不再次接触磁盘的情况下从快照绘制树形图的方式。

• 不存在的路径 = 退出代码 0 且没有文件。 没有可检查的错误代码：您必须验证输出文件是否已创建。

• 存在一个全局互斥体（WizTreeMutex）：调用通过锁进行序列化。

• 重复文件查找器仅存在于 GUI 中。 二进制文件包含 Duplicate Files:、Duplicates only、DUPSIZE/DUPCOUNT 列以及 INI 键 dupmethod，但没有命令行开关可以访问它们。因此，wiztree_duplicates 不会调用 WizTree：它按大小对快照进行分组，并且只从磁盘读取与其他文件共享大小的文件。

• /exportlimit=N 会按遍历顺序将导出截断为 N 行，而不是全局前 N 名。这就是为什么排名是在这里通过流式处理 CSV 完成的，而不是由 WizTree 完成。

• /sortby 值：0 无顺序，1 大小，2 已分配，3 修改日期。

许可证

MIT。WizTree 是 Antibody Software 的软件，根据其自己的许可证分发：本项目仅调用其命令行。