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

Related MCP server: WizTree MCP

Установка

Требуется 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; инструменты MCP не вызываются в режиме Ask.

Подключение к 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 профиля или в домашнем файле 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: рисуемом владельцем контроле, где строки не существуют как текст, а рисуются на лету. Извне процесса они являются пикселями, а не данными. Результаты, которые вы видите на экране, не читаемы.

Что окно действительно предоставляет через обычные сообщения 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 только в headless-режиме (с /export или /treemapimagefile). Запущенный без переключателей, он не открывает GUI с этим CSV; он возвращается к диску по умолчанию. В GUI CSV открывается из выпадающего списка дисков, пункт <CSV File>.

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

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

• Процесс без повышения прав (обычный случай с Cursor): WizTree переключается на рекурсивное сканирование папок. На C:\ это может занять несколько минут; для отдельной папки это всё ещё быстро (~500 тыс. файлов за 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 в качестве пути сканирования работает: именно так treemap-изображения строятся из снимка, не обращаясь к диску снова.

• Несуществующий путь = код возврата 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, распространяемая под собственной лицензией: этот проект лишь вызывает её командную строку.