wizTree MCP

Cómo funciona

wizTreeMCP es un servidor MCP en Python que controla WizTree desde un LLM. Puedes conectarlo a Claude Code, Cursor o DeepSeek Harness y preguntar en lenguaje natural "¿qué está ocupando espacio en la unidad C:?", "encuentra todos los archivos de más de 1 GB en Descargas", "¿cuánto espacio ocupan los vídeos en esta carpeta?", "¿hay dependencias huérfanas de Python que pueda limpiar?".

Lo encuentro muy útil para limpiar cachés sin usar de wsl, python, docker y npm. Usa modelos locales para una mejor privacidad

Un solo archivo: wiztree_mcp.py. Funciona solo en Windows, porque WizTree es una aplicación de Windows.

WizTree no tiene API: tiene una línea de comandos que exporta un CSV de todo lo que ha escaneado. El servidor usa eso.

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

Un escaneo se ejecuta una vez y se guarda como una instantánea CSV en la caché. Todas las preguntas posteriores se responden leyendo ese CSV en streaming: no se vuelve a escanear el disco, ni se carga toda la unidad en memoria. Una instantánea de medio millón de archivos ocupa ~50 MB y responde a una consulta en aproximadamente un segundo.

Las instantáneas se reutilizan automáticamente: si escaneaste C:\ y luego preguntas algo sobre C:\Users\me\Downloads, el servidor reutiliza la instantánea existente en lugar de hacer el trabajo de nuevo.

Related MCP server: WizTree MCP

Instalación

Requiere Python 3.10+.

cd wiztree-mcp
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt

El entorno virtual ya se ha creado en .venv: si eso es suficiente para ti, ya está listo.

El servidor encuentra WizTree64.exe por sí solo si la carpeta wiztree-mcp está dentro de la carpeta portable de WizTree, o si WizTree está instalado en Program Files. De lo contrario, indícalo con la variable de entorno WIZTREE_EXE.

Conexión con Claude Code

Un solo comando, sin editar JSON — se encarga de la fusión:

claude mcp add wiztree --scope user -- "C:\path\to\wiztree-mcp\.venv\Scripts\python.exe" "C:\path\to\wiztree-mcp\wiztree_mcp.py"

--scope controla dónde se guarda el registro:

Verifica:

claude mcp list

Luego sal y reinicia claude: los servidores MCP se conectan al inicio de la sesión, nunca en caliente. Dentro de la sesión, las herramientas se llaman mcp__wiztree__wiztree_scan y similares, pero no necesitas nombrarlas: solo pregunta "¿qué está usando espacio en D:".

Si prefieres el ámbito de proyecto sin la CLI, también puedes escribir un .mcp.json a mano en la carpeta desde la que lanzas claude, con la misma estructura que se muestra a continuación para Cursor. En la primera sesión, Claude Code te pedirá que lo apruebes, porque un .mcp.json de proyecto no se confía automáticamente.

Conexión con 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"
      }
    }
  }
}

Apunta a .venv\Scripts\python.exe, no al python del sistema: así no necesitas activar el entorno y Cursor siempre encuentra las dependencias.

El archivo cursor-mcp.json ya contiene el fragmento con las rutas absolutas correctas para esta instalación: ábrelo y cópialo.

O deja que el script lo haga — conserva otros servidores ya configurados y hace una copia de seguridad:

.venv\Scripts\python.exe install_mcp.py

Reinicia Cursor: en la lista de MCP deberías ver wiztree con 16 herramientas. Se requiere el modo Agente; las herramientas MCP no se llaman en modo Preguntar.

Conexión con DeepSeek Harness

Aquí el JSON que usan los otros dos clientes no se aplica, así que copiar la configuración de Cursor y cambiar las rutas no funcionará. DeepSeek Harness (dsh) no tiene una clave mcpServers: monta cada servidor MCP como una instancia de plugin de @deepseek-ai/dsh-mcp-client en un archivo YAML. Una instancia de plugin = un servidor MCP.

La entrada que hay que añadir a la lista:

- 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

El archivo dsh-cordis-patch.yml ya tiene las rutas absolutas listas.

Dónde colocarlo: en el cordis.patch.yml del perfil, o en el del directorio base del harness ($DSH_HOME, por defecto ~/.dsh). Las capas se apilan en este orden: paquete de perfil, cordis.patch.yml del perfil, cordis.patch.yml del directorio base del harness y, finalmente, las superposiciones pasadas con --patch. Comprueba el resultado efectivo con dsh --dump-config.

Tres cosas que importan aquí:

• toolCallTimeoutMs: 900000. El valor predeterminado es 60000 ms, un minuto. Escanear una unidad completa sin privilegios de administrador lleva mucho más tiempo y la llamada se cortaría a la mitad. Los otros clientes no tienen un límite tan estricto.

• Rutas de Windows sin comillas dobles. En YAML, las comillas dobles interpretan secuencias de escape, así que "C:\Users\..." falla al analizarse en \U. Sin comillas, o con comillas simples, las barras invertidas se mantienen literales.

• Los nombres de las herramientas se convierten en mcp__wiztree__wiztree_scan y así sucesivamente, la misma convención que Claude Code.

DeepSeek Harness está en vista previa para desarrolladores, por lo que este formato puede cambiar entre versiones: si algo no coincide, compara con la documentación oficial de MCP.

Herramientas

Todas las herramientas de consulta aceptan path, refresh, max_age_minutes, admin, filter, filter_exclude, timeout_seconds y escanean por su cuenta si no encuentran una instantánea válida: el LLM puede ir directamente a wiztree_top_files sin llamar primero a wiztree_scan.

Usar la GUI y la IA juntas

Puedes mantener la ventana de WizTree abierta, hacer clic y hacer preguntas desde el chat al mismo tiempo. Funciona, pero vale la pena saber hasta dónde llega.

WizTree dibuja la lista de archivos en un TVirtualDrawTree: un control dibujado por el propietario donde las filas no existen como texto, sino que se pintan sobre la marcha. Desde fuera del proceso son píxeles, no datos. Los resultados que ves en pantalla no son legibles.

Lo que la ventana expone a través de mensajes Win32 normales es hacia dónde apunta, y eso es suficiente:

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

Así que el flujo es: haces clic en [D:] en la GUI → preguntas "¿qué está usando espacio aquí?" → wiztree_gui_state lee que la ventana apunta a D: → las otras herramientas responden sobre D:. No necesitas escribir ninguna ruta.

Dos formas de compartir datos con la ventana abierta:

• Re-escaneo (cero fricción). El servidor escanea por su cuenta el destino que lee de la GUI. Cuesta el tiempo de un escaneo.

• Transferencia CSV (instantánea). En la GUI haz File > Export, luego wiztree_import_csv. Sin re-escaneo, y si la GUI se ejecutaba como administrador, heredas el escaneo MFT. Esta es la forma más rápida de trabajar en una unidad completa.

Ambos enfoques coexisten: se verificó que una exportación de línea de comandos se ejecuta en medio segundo mientras una ventana de WizTree está abierta, sin molestarla — el mutex global no bloquea instancias concurrentes.

Nota: WizTree64.exe ruta.csv carga el CSV solo en modo sin interfaz (con /export o /treemapimagefile). Si se inicia sin modificadores, no abre la GUI con ese CSV; vuelve a una unidad predeterminada. En la GUI, el CSV se abre desde el menú desplegable de unidades, entrada <CSV File>.

Escaneos rápidos: admin

En volúmenes NTFS, WizTree lee el MFT directamente, por eso escanea una unidad completa en segundos. Pero leer el MFT requiere privilegios de administrador.

• Proceso sin elevar (el caso normal con Cursor): WizTree recurre a un escaneo recursivo de carpetas. En C:\ puede tardar varios minutos; en una sola carpeta sigue siendo rápido (~500 000 archivos en 5 segundos).

• admin: true: WizTree se relanza con privilegios elevados y usa el MFT. Esto activa el aviso de UAC de Windows, que debe aceptarse manualmente.

Si necesitas esto con frecuencia, inicia Cursor como administrador: el servidor hereda la elevación y todos los escaneos son inmediatos sin más avisos. wiztree_info te indica en qué situación estás.

Variables de entorno

Pruebas

.venv\Scripts\python.exe test_smoke.py

Inicia el servidor por stdio exactamente como lo hace Cursor, crea una prueba (con espacios y comas en los nombres) y ejercita las 16 herramientas: 37 comprobaciones.

Para probarlo con datos reales:

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

Detalles de implementación que pueden ahorrarte tiempo

Cuestiones descubiertas en la práctica al trabajar con la CLI de WizTree 4.32, no documentadas en ningún sitio:

• Los encabezados CSV están localizados. En italiano, la primera columna se llama Nome file, no File Name. Las primeras 7 columnas están siempre en el mismo orden, mientras que las opcionales (DRIVECAPACITY, CREATEDDATE, MFTRECNO, …) mantienen un nombre ASCII estable. El analizador se basa en la posición para las primeras columnas y en el nombre para las demás.

• No uses comillas dentro de los argumentos. Pasar /export="C:\out.csv" desde subprocess hace que WizTree abra una ventana de error modal invisible y el proceso se cuelgue para siempre. Los valores deben pasarse sin comillas (/export=C:\out.csv) y dejar que Python se encargue de las comillas para CreateProcess.

• Los archivos sin extensión se exportan con un punto final: payload se convierte en payload.. Windows no permite puntos finales en los nombres, así que el analizador lo elimina.

• WizTree puede releer sus propios CSV. Pasar un .csv exportado como ruta de escaneo funciona: así es como se dibujan los mapas de árbol desde una instantánea sin volver a tocar el disco.

• Ruta inexistente = código de salida 0 y ningún archivo. No hay ningún código de error que comprobar: debes verificar que el archivo de salida se haya creado.

• Existe un mutex global (WizTreeMutex): las invocaciones se serializan con un bloqueo.

• El buscador de duplicados solo existe en la GUI. El binario contiene Duplicate Files:, Duplicates only, las columnas DUPSIZE/DUPCOUNT y la clave INI dupmethod, pero ningún modificador de línea de comandos llega hasta ellas. Por eso wiztree_duplicates no llama a WizTree: agrupa por tamaño desde la instantánea y lee del disco solo los archivos que comparten tamaño con otro.

• /exportlimit=N trunca la exportación a N filas en orden de recorrido, no un top-N global. Por eso la clasificación se hace aquí, en streaming sobre el CSV, y no con WizTree.

• Valores de /sortby: 0 sin orden, 1 tamaño, 2 asignado, 3 fecha de modificación.

Licencia

MIT. WizTree es software de Antibody Software, distribuido bajo su propia licencia: este proyecto solo invoca su línea de comandos.