wizTree MModel Context Protocol

Cómo funciona

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

A mí me resulta muy útil para limpiar archivos de caché sin usar de wsl, python, docker, npm.

Un único 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 sola 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 una consulta en aproximadamente un segundo.

Las instantáneas se reutilizan automáticamente: si escaneas 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.

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 con eso te basta, ya estás listo.

El servidor encuentra WizTree64.exe por su cuenta si la carpeta wiztree-mcp está dentro de la carpeta portátil de WizTree, o si WizTree está instalado en Program Files. De lo contrario, indícaselo con la variable de entorno WIZTREE_EXE.

Conexión con Claude Code

Un 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 cierra 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 usar 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 abajo 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

Abre la configuración del MCP de Cursor (Configuración → MCP → Añadir nuevo servidor MCP) o crea %USERPROFILE%\.cursor\mcp.json manualmente para una configuración global, o .cursor\mcp.json dentro de un proyecto para configurarlo solo allí:

{
  "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 encuentra siempre las dependencias.

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

O deja que el script lo haga — conserva los demás 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. El modo Agent es obligatorio; las herramientas MCP no se invocan en el modo Ask.

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 la 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 preparadas.

Dónde colocarlo: en el cordis.patch.yml del perfil, o en el de la carpeta del harness ($DSH_HOME, por defecto ~/.dsh). Las capas se acumulan en este orden — paquete de perfil, cordis.patch.yml del perfil, cordis.patch.yml del harnesso, y finalmente los overlays pasados con --patch. Comprueba el resultado con dsh --dump-config.

Tres cosas importantes aquí:

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

• Rutas de Windows sin comillas dobles. En YAML, las dobles comillas interpretan secuencias de escape, por lo que "C:\Users\..." falla al parsear en \U. Sin comillas, o con comillas simples, las barras invertidas literal.

• Los nombres de las herramientas son mcp__wiztree__wiztree_scan y demás, la misma convención que en Claude Code.

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

Herramientas

Todas las herramientas de consulta aceptan path, refresh, max_age_minutes, admin, filter, filter_exclude y 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 antes a wiztree_scan.

Usar la GUI y la IA juntas

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

WizTree dibuja la lista de archivos en un TVirtualDrawTree: un control dibujado por el usuario donde las filas no existen como texto, sino que se pintan sobre la marcha. From outside the process they are pixels, not data. Los resultados que ves en la pantalla no son legibles.

Lo que la ventana sí expone mediante los mensajes normales de Win32 y de apuntar, and thatfor is "which a pretty".

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 esquema es: haces clic [D:] en la GUI → preguntas "¿qué está usando espacio?" → wiztree_gui_state lee que la ventana apunta a D: → the rest of the tools answer about D:.

Don't need to write any ruta.

Dos formas de compartir datos con la ventana abierta:

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

• CSV handoff (instantáneo). En la GUI haz File > Export, luego la nota import. No se resuelve a escanear y, si la GUI estaba activa como administrador, heredas el escaneo de la MFT. works Esta es la forma más rápida de trabajar con una unidad completa.

Ambas formas conviven: se comprobó que una exportación desde la línea de comandos se ejecuta en medio segundo mientras la ventana de WizTree abierta, sin perturbarla — the global mutex does not block concurrent instances.

Nota: WizTree64.exe path.csv carga el CSV solo en modo sin interfaz (con /export o /treemapimagefile). Si se inicia sin opciones, no abre la GUI con ese CSV; recurre a una unidad por defecto. En la GUI el CSV se abre desde el desplegable de unidades, en la entrada <CSV File>.

Escaneos rápidos: admin

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

• Proceso no elevado (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 elevado y usa la MFT. Esto activa el aviso de UAC de Windows, que debe aceptarse manualmente.

Si lo necesitas a menudo, inicia Cursor como administrador: el servidor hereda la elevación y todos los escaneos se vuelven inmediatos sin más avisos. wiztree_info te indica en qué situación te encuentras.

Variables de entorno

Pruebas

.venv\Scripts\python.exe test_smoke.py

Inicia el servidor a través de stdio exactamente como lo hace Cursor, crea un árbol de 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

Descubrimientos hechos en la práctica al trabajar con la CLI de WizTree 4.32, no documentados en ningún sitio:

• Los encabezados del 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.

• Sin 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 haga 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í se dibujan los mapas de árbol desde una instantánea sin tocar el disco de nuevo.

• Ruta inexistente = código de salida 0 y sin archivo. No hay un código de error que comprobar: debes verificar que el archivo de salida se creó.

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

• El buscador de duplicados existe solo en la GUI. El binario contiene Duplicate Files:, Duplicates only, las columnas DUPSIZE/DUPCOUNT, y la clave INI dupmethod, pero no hay ninguna opción de línea de comandos que llegue a ellos. Por lo tanto, wiztree_duplicates no llama a WizTree: agrupa por tamaño desde la instantánea y lee del disco solo los archivos que comparten un tamaño con otros.

• /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 flujo 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 un software de Antibody Software, distribuido bajo su propia licencia: este proyecto solo invoca su línea de comandos.