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

スキャンは一度だけ実行され、CSV スナップショットとしてキャッシュに保存されます。 後続の質問はすべて、その CSV をストリーミングで読み取って回答されます。ディスクの 再スキャンも、ドライブ全体をメモリに読み込むこともありません。50 万ファイルのスナップショットは 約 50 MB で、クエリには約 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 編集不要の 1 コマンド — マージも処理します:

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 リストに wiztree と 16 個のツールが表示されるはずです。Agent モードが必要です。 Ask モードでは MCP ツールは呼び出されません。

DeepSeek Harness への接続

ここでは、他の 2 つのクライアントで使用される JSON は適用されません。Cursor の設定をコピーして パスを変更しても機能しません。DeepSeek Harness (dsh) には mcpServers キーがありません。各 MCP サーバーを YAML ファイル内の @deepseek-ai/dsh-mcp-client のプラグインインスタンスとしてマウントします。 1 つのプラグインインスタンス = 1 つの 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 で有効な結果を確認してください。

ここで重要な 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 は、CSV をヘッドレスモード（/export または /treemapimagefile 使用時）でのみ読み込みます。スイッチなしで起動した場合、その CSV で GUI は開かれず、デフォルトドライブにフォールバックします。GUI では、CSV はドライブのドロップダウンの <CSV File> エントリから開きます。

高速スキャン: 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 件ではありません。そのため、ランキングは WizTree ではなく、ここで CSV をストリーミング処理して行われます。

• /sortby の値: 0 順序なし、1 サイズ、2 割り当て、3 更新日時。

ライセンス

MIT。WizTree は Antibody Software によるソフトウェアで、独自のライセンスの下で配布されています。このプロジェクトはコマンドラインを呼び出すだけです。