wizTree MCP

작동 방식

wizTreeMCP는 WizTree를 LLM에서 구동하는 Python MCP 서버입니다. Claude Code, Cursor, DeepSeek Harness에 연결할 수 있으며 자연어로 "C: 드라이브에서 공간을 차지하는 것은 무엇인가요?", "Downloads에서 1GB가 넘는 모든 파일을 찾아줘", "이 폴더에서 비디오가 차지하는 공간은 얼마인가요?", *"정리할 수 있는 Python 고아 의존성이 있나요?"*라고 물어볼 수 있습니다.

wsl, python, docker, npm 사용하지 않는 캐시 파일 정리에 매우 유용합니다.

단일 파일: wiztree_mcp.py. WizTree가 Windows 응용 프로그램이므로 Windows에서만 작동합니다.

WizTree에는 API가 없습니다. 스캔한 모든 것을 CSV로 내보내는 명령줄이 있습니다. 서버는 이를 사용합니다.

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

스캔은 한 번 실행되며 캐시에 CSV 스냅샷으로 저장됩니다. 이후의 모든 후속 질문은 해당 CSV를 스트리밍 방식으로 읽어서 답변합니다. 디스크를 다시 스캔하지 않으며, 전체 드라이브를 메모리에 로드하지도 않습니다. 50만 개 파일의 스냅샷은 ~50MB를 차지하며 쿼리에 약 1초가 걸립니다.

스냅샷은 자동으로 재사용됩니다. 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"
      }
    }
  }
}

시스템 python이 아닌 .venv\Scripts\python.exe를 가리키세요. 그렇게 하면 환경을 활성화할 필요가 없으며 Cursor가 항상 의존성을 찾을 수 있습니다.

cursor-mcp.json 파일에는 이 설치에 대한 올바른 절대 경로가 포함된 스니펫이 이미 들어 있습니다. 열어서 복사하세요.

또는 스크립트가 대신 처리하게 하세요 — 이미 구성된 다른 서버를 유지하고 백업을 만듭니다:

.venv\Scripts\python.exe install_mcp.py

Cursor를 다시 시작하세요: MCP 목록에 16개의 도구가 있는 wiztree가 표시되어야 합니다. 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 또는 하네스 홈 디렉토리 ($DSH_HOME, 기본값 ~/.dsh)에 넣으세요. 레이어는 다음 순서로 쌓입니다 — 프로필 번들, 프로필 cordis.patch.yml, 하네스 홈 cordis.patch.yml, 마지막으로 --patch로 전달된 오버레이. dsh --dump-config로 실제 결과를 확인하세요.

여기서 중요한 세 가지:

• toolCallTimeoutMs: 900000. 기본값은 60000ms, 1분입니다. 관리자 권한 없이 전체 드라이브를 스캔하는 데는 훨씬 더 오래 걸리며 호출이 중간에 끊길 수 있습니다. 다른 클라이언트에는 이렇게 짧은 제한이 없습니다.

• 따옴표 없는 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_scan을 호출하지 않고 바로 wiztree_top_files로 갈 수 있습니다.

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 창이 열린 상태에서 0.5초 만에 실행되는 것이 확인되었으며, 창을 방해하지 않습니다 — 전역 뮤텍스가 동시 인스턴스를 차단하지 않습니다.

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.