wizTree MCP

Как это работает

wizTreeMCP — это Python MCP-сервер, который управляет WizTree из LLM. Вы можете подключить его к Claude Code, Cursor или DeepSeek Harness и задавать вопросы на естественном языке: «что занимает место на диске C:?», «найти все файлы больше 1 ГБ в Downloads», «сколько места занимают видео в этой папке?», «есть ли осиротевшие зависимости 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 МБ и отвечает на запрос примерно за секунду.

Снимки переиспользуются автоматически: если вы просканировали 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: если этого достаточно, вы готовы к работе.

Сервер сам находит WizTree64.exe, если папка wiztree-mcp находится внутри переносимой папки WizTree или если WizTree установлен в Program Files. В противном случае укажите его с помощью переменной окружения 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, вы также можете вручную создать .mcp.json в папке, из которой запускаете claude, с той же структурой, что показана ниже для 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; в режиме Ask инструменты MCP не вызываются.

Подключение к DeepSeek Harness

Здесь JSON, используемый двумя другими клиентами, не подходит, поэтому копирование конфигурации Cursor и изменение путей не сработает. У DeepSeek Harness (dsh) нет ключа mcpServers: он подключает каждый MCP-сервер как экземпляр плагина @deepseek-ai/dsh-mcp-client в YAML-файле. Один экземпляр плагина = один 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 профиля или в домашний cordis.patch.yml harness ($DSH_HOME, по умолчанию ~/.dsh). Слои накладываются в таком порядке: бандл профиля, cordis.patch.yml профиля, домашний cordis.patch.yml harness и, наконец, оверлеи, переданные с помощью --patch. Проверьте итоговый результат с помощью dsh --dump-config.

Три важных момента:

• toolCallTimeoutMs: 900000. По умолчанию стоит 60000 мс, одна минута. Сканирование всего диска без прав администратора занимает гораздо больше времени, и вызов оборвался бы на полпути. У других клиентов нет такого жёсткого ограничения.

• Пути Windows без двойных кавычек. В YAML двойные кавычки интерпретируют escape-последовательности, поэтому "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 и ИИ

Вы можете оставить окно WizTree открытым, кликать по интерфейсу и одновременно задавать вопросы из чата. Это работает, но стоит понимать, насколько далеко это заходит.

WizTree отрисовывает список файлов в TVirtualDrawTree: это owner-drawn элемент управления, в котором строки существуют не как текст, а рисуются на лету. Извне процесса это пиксели, а не данные. Результаты, которые вы видите на экране, невозможно прочитать.

А вот что окно предоставляет через обычные сообщения 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

Итак, процесс такой: вы кликаете [D:] в GUI → спрашиваете «что занимает место здесь?» → wiztree_gui_state считывает, что окно указывает на D: → остальные инструменты отвечают про D:. Вам не нужно вводить никакой путь.

Два способа обмена данными при открытом окне:

• Повторное сканирование (без усилий). Сервер самостоятельно сканирует цель, которую он считывает из GUI. Это стоит времени одного сканирования.

• Передача через CSV (мгновенно). В GUI выберите File > Export, затем wiztree_import_csv. Без повторного сканирования, а если GUI был запущен с правами администратора, вы переносите и скан MFT. Это самый быстрый способ работы с полностью заполненным диском.

Оба подхода сосуществуют: было проверено, что экспорт из командной строки выполняется за полсекунды, пока окно WizTree открыто, не мешая ему — глобальный мьютекс не блокирует параллельные экземпляры.

Примечание: WizTree64.exe path.csv загружает CSV только в пакетном режиме (с /export или /treemapimagefile). Запущенный без флагов, он не открывает GUI с этим CSV; он возвращается к диску по умолчанию. В GUI CSV открывается из выпадающего списка дисков, пункт <CSV File>.

Быстрые сканирования: admin

На томах NTFS WizTree читает MFT напрямую, поэтому он сканирует весь диск за секунды. Но чтение MFT требует прав администратора.

• Неповышенный процесс (обычный случай с Cursor): WizTree переключается на рекурсивное сканирование папок. На C:\ это может занять несколько минут; для одной папки это всё ещё быстро (~500 000 файлов за 5 секунд).

• admin: true: WizTree перезапускается с повышением прав и использует MFT. Это вызывает запрос UAC Windows, который необходимо принять вручную.

Если вам это нужно часто, запустите 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"

Детали реализации, которые могут сэкономить вам время

Вещи, обнаруженные на практике при работе с CLI WizTree 4.32, нигде не задокументированные:

• Заголовки CSV локализованы. В итальянской версии первый столбец называется Nome file, а не File Name. Первые 7 столбцов всегда в одном и том же порядке, в то время как необязательные (DRIVECAPACITY, CREATEDDATE, MFTRECNO, …) сохраняют стабильное ASCII-имя. Парсер полагается на позицию для первых столбцов и на имя для остальных.

• Никаких кавычек внутри аргументов. Передача /export="C:\out.csv" из subprocess заставляет 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 строк в порядке обхода, а не глобальный top-N. Именно поэтому ранжирование выполняется здесь, в потоковой обработке CSV, а не WizTree.

• Значения /sortby: 0 без порядка, 1 размер, 2 выделено, 3 дата изменения.

Лицензия

MIT. WizTree — это программное обеспечение Antibody Software, распространяемое по собственной лицензии: этот проект только вызывает его командную строку.