wizTree MCP

仕組み

wizTreeMCP は、WizTree を LLM から操作する Python 製 MCP サーバーです。 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

スキャンは 1 回だけ 実行され、CSV スナップショット としてキャッシュに保存されます。 後続の質問はすべて、その CSV をストリーミング読み込みして回答されます。ディスクの 再スキャンも、ドライブ全体をメモリに読み込むこともありません。50 万ファイルのスナップショットは 約 50 MB で、クエリには約 1 秒かかります。

スナップショットは自動的に再利用されます: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 にすでに作成されています:それで十分なら、そのまま使えます。

サーバーは、wiztree-mcp フォルダが WizTree ポータブル版フォルダの内側にある場合は WizTree64.exe を自動的に見つけ、WizTree が Program Files にインストールされている場合も同様です。それ以外の場合は、 WIZTREE_EXE 環境変数で指定します。

Claude Code への接続

コマンド 1 つで、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 用のものと同じです。 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 への接続

ここでは、他の 2 つのクライアントで使う JSON は 適用されません。そのため、Cursor の設定をコピーして パスを変更しても機能しません。DeepSeek Harness(dsh)には mcpServers キーはなく、各 MCP サーバーを YAML ファイル内の プラグインインスタンス としてマウントします。 プラグイン 1 つ = MCP サーバー 1 つです。

リストに追加するエントリ:

- 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 で実際の結果を確認できます。

ここで重要な 3 つの点:

• toolCallTimeoutMs: 900000。 デフォルトは 60000 ms(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: について回答する。 パスを入力する必要はありません。

ウィンドウを開いたままデータを共有する 2 つの方法:

• 再スキャン(手間ゼロ)。 サーバーは GUI から読み取ったターゲットを独自にスキャンします。 スキャン 1 回分の時間がかかります。

• CSV ハンドオフ(即時)。 GUI で File > Export を実行し、その後 wiztree_import_csv を呼びます。 再スキャンは不要で、GUI が管理者として実行されていた場合は MFT スキャンの結果も引き継がれます。これはフルドライブで作業する最速の方法です。

両方のアプローチは共存できます:WizTree ウィンドウが開いている間にコマンドラインエクスポートが 0.5 秒で実行されることが確認されており、ウィンドウを妨げることはありません — グローバルミューテックスは 並行インスタンスをブロックしないためです。

注: WizTree64.exe path.csv は、ヘッドレスモード(/export または /treemapimagefile 指定時)でのみCSVを読み込みます。スイッチなしで起動した場合、その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

Cursor とまったく同じ方法で stdio 経由でサーバーを起動し、(名前にスペースとカンマを含む)テストツリーを作成して、16個すべてのツールを実行します: 37チェック。

実データで試すには:

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

時間を節約できる実装の詳細

WizTree 4.32 CLI を扱う現場で発見された、どこにも文書化されていない事柄:

• CSVヘッダーはローカライズされています。 イタリア語では最初の列は File Name ではなく Nome file と呼ばれます。最初の7列は常に同じ順序ですが、オプションの列(DRIVECAPACITY、CREATEDDATE、MFTRECNO、…)は安定したASCII名を保持します。パーサーは最初の列については位置に依存し、その他の列については名前に依存します。

• 引数内に引用符は使えません。 subprocess から /export="C:\out.csv" を渡すと、WizTree は目に見えないモーダルエラーウィンドウを開き、プロセスは永久にハングします。値は裸で渡し(/export=C:\out.csv)、CreateProcess の引用符付けは Python に任せる必要があります。

• 拡張子のないファイルは末尾にドットが付いてエクスポートされます: 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 のソフトウェアであり、独自のライセンスの下で配布されています。このプロジェクトはそのコマンドラインを呼び出すだけです。