Cómo instalar DesktopCommanderMCP: búsqueda de archivos de Claude Code, control de terminal y configuración de edición diferencial

DesktopCommanderMCP es un servidor MCP local que permite a Claude Code, Codex y otros clientes compatibles buscar archivos, leer y editar texto, ejecutar comandos de terminal y ver el resultado de tareas largas. Es adecuado para escenarios en los que “dejar que la IA complete la recuperación, modificación y verificación en un espacio de trabajo designado”, en lugar de entregar incondicionalmente toda la computadora al modelo.

Apareció en GitHub Trending esta semana, lo que indica que los desarrolladores están prestando más atención; pero es más importante comprender los permisos antes de la instalación: el comando se ejecutará como el usuario actual que inició el servidor. Por lo tanto, primero limite el directorio de trabajo y el alcance de la autorización y luego piense en la automatización.

Qué puede hacer DesktopCommanderMCP

Según la descripción del proyecto, además de las capacidades estándar del sistema de archivos MCP, complementa las siguientes capacidades comunes:

Busque recursivamente archivos y contenido de texto, que se pueden utilizar para la ubicación de la base del código;
Se puede utilizar el reemplazo de texto de rango pequeño y la edición de múltiples archivos para la modificación diferencial;
Ejecute comandos de terminal, transmita resultados de lectura, ejecución en segundo plano y gestión de procesos;
Realice una lectura paginada de resultados de archivos grandes para reducir la cantidad de contenido incluido en el contexto a la vez;
Leer y procesar archivos comunes como CSV, JSON, Excel, PDF, DOCX, etc.;
La herramienta llama a registros de auditoría, listas de bloques de comandos y protección de enlaces simbólicos para operaciones de archivos.

Estas capacidades no significan que todos los clientes mostrarán la herramienta de la misma manera, ni que todas las operaciones deban aprobarse automáticamente. Cuanto más pueda hacer, más importante será dejar que el modelo describa primero el comando que se ejecutará, la ruta de destino y los cambios esperados.

Control de seguridad antes de la instalación.

Complete estos elementos primero antes de agregar el MCP:

Instale Node.js y verifique que npx esté disponible en la terminal.
Cree un directorio de proyecto independiente para su trabajo de IA; no lo exponga inicialmente a su directorio de inicio personal, directorio de descargas o directorio de configuración que contenga credenciales.
Confirme la política de permisos del cliente: los comandos de alto riesgo, las eliminaciones, las solicitudes de red y las modificaciones masivas deben requerir confirmación.
Pruebe únicamente en repositorios confiables o copias de trabajo restaurables; comprometer proyectos importantes a Git o crear copias de seguridad primero.
Para un aislamiento más fuerte, priorice Docker y monte solo las carpetas que claramente necesite.

No coloque claves API, claves privadas, perfiles de navegador, bibliotecas criptográficas o archivos de configuración de producción en directorios de libre búsqueda. Los comandos de DesktopCommanderMCP se ejecutan con sus derechos de usuario. MCP no es un entorno limitado seguro.

Comando de instalación de Claude Code

Ejecutar en la terminal:

1

claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

--scope user significa agregar el servidor al alcance del usuario actual. Si solo desea que el proyecto actual lo use, elimine --scope user y luego ejecútelo en el directorio del proyecto. Reinicie Claude Code después de la instalación o confirme en la lista de MCP del cliente que desktop-commander está conectado.

La primera vez que lo uses puedes darle una tarea de bajo riesgo, por ejemplo:

Busque únicamente archivos TypeScript que contengan TODO en el proyecto actual, indique la ruta y el número de línea, no modifique el archivo y no ejecute el comando.

Confirme que los resultados de la búsqueda de archivos sean los esperados antes de permitirle realizar pruebas o ediciones diferenciales.

Instalación de Codex y configuración de TOML

Para Codex, puedes ejecutar directamente:

1

codex mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

También puedes escribir ~/.codex/config.toml manualmente:

1
2
3


[mcp_servers.desktop-commander]
command = "npx"
args = ["-y", "@wonderwhy-er/desktop-commander@latest"]

Después de la configuración manual, abra una nueva sesión de Codex y verifique si el MCP está cargado. Si el proyecto solo necesita un uso temporal, dé prioridad a la configuración a nivel de proyecto o de sesión; No exponga permanentemente herramientas de archivos con altos privilegios a todos los proyectos para la tarea de depuración de un almacén.

Cómo utilizar la búsqueda de archivos y la edición diferencial

El valor de DesktopCommanderMCP no es “permitir que el modelo reescriba directamente todo el almacén”, sino limitar el alcance primero y luego producir cambios revisables. Un pedido seguro es:

Primero especifique el directorio raíz del proyecto al que se le permite acceder.
Se solicita al modelo que primero busque palabras clave y enumere los archivos de resultados.
Deje que lea la cantidad mínima de código y pruebas relevantes.
Solicite explícitamente realizar solo un cambio lógico y muestre la diferencia.
Revise la diferencia antes de permitir que se escriban y ejecuten pruebas específicas.

Por ejemplo:

Busque en el almacén actual el punto de llamada de createClient. Enumere primero la ruta, el propósito y los archivos de prueba; no escribas. Una vez confirmado, reemplace la URL base solo en el archivo responsable de la inicialización de la API y muestre las diferencias. No modifique el archivo de bloqueo ni formatos extraños.

Este tipo de directiva es más controlable que “arreglar la configuración de API”: los rangos de ruta, los objetivos de modificación, las prohibiciones y las acciones de validación son todos claros.

Cómo controlar comandos largos y procesos en segundo plano

La herramienta admite transmisión de salida de comandos, ejecución en segundo plano, listas de procesos y detención de procesos, lo que la hace adecuada para crear, desarrollar servidores o probar tareas más largas. Pero los procesos a largo plazo no deben dejarse desatendidos.

Sugerencias:

Comience ejecutando un comando de solo lectura o de corta duración, como git status, un único archivo de prueba o un ensayo de la compilación;
Establezca un tiempo de espera razonable para el comando, no establezca la ejecución predeterminada de forma indefinida;
Antes de iniciar un servidor de desarrollo, una migración o un script por lotes, solicite que el modelo especifique el puerto, la ruta de escritura y el método de detención;
Vea las páginas de inicio de sesión, no complete el registro de compilación completo con el modelo;
Una vez finalizado, confirme que el proceso en segundo plano haya salido para evitar la ocupación del puerto o dejar atrás procesos secundarios.

Si el modelo propone un comando para eliminar, restablecer, sobrescribir, cargar, implementar o acceder a producción, debe detenerse en el punto de confirmación. El hecho de que la herramienta pueda ejecutarse no significa que la operación haya sido autorizada por el negocio.

¿Cuándo es adecuado el aislamiento de Docker?

Si no desea instalar Node.js localmente o si desea limitar el rango visible de archivos, puede utilizar el método Docker proporcionado por el proyecto. La configuración básica es la siguiente:

1
2
3
4
5
6
7
8


{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/desktop-commander:latest"]
    }
  }
}

Esta configuración básica no monta el directorio local, por lo que los archivos del host no se pueden editar directamente. Cuando necesite operar un proyecto, monte solo un directorio claro, como un espacio de trabajo, y asígnelo a una ruta fija en el contenedor; no monte todo el directorio de usuarios, el directorio raíz o el directorio de credenciales. Docker puede reducir el alcance del mal funcionamiento, pero el directorio montado seguirá siendo modificado por comandos dentro del contenedor.

Solución de problemas comunes

El cliente no ve la herramienta MCP

Verifique si Node.js y npx se pueden ejecutar, confirme que el archivo de configuración esté escrito en la ubicación donde el cliente correspondiente realmente lo lee y luego reinicie el cliente o abra una nueva sesión. También verifique que la configuración de MCP sea JSON/TOML válido y que no haya entradas de servidor en conflicto con el mismo nombre.

`npx` se inicia lentamente o falla cada vez que se instala.

Primero ejecútelo por separado en la terminal:

1

npx -y @wonderwhy-er/desktop-commander@latest

Observe si Node.js, la red, la caché npm o el proxy empresarial están causando el problema. No atribuya “el cliente no se conecta” directamente a la configuración de MCP; Primero asegúrese de que se inicie el comando, luego regrese al registro del cliente para verificar la conexión estándar.

La modelo buscó archivos que no deberían verse.

Detenga la sesión de MCP inmediatamente y verifique el espacio de trabajo del cliente, el directorio de inicio y el directorio de montaje de Docker. Luego, limite las rutas accesibles, saque los archivos confidenciales y vuelva a probar la búsqueda de solo lectura. No confíe en “no mirar” en palabras rápidas como sustituto del aislamiento de rutas y permisos.

La edición de diferencias cambia demasiado

Primero restaure al estado conocido de Git o use la diferencia del editor para deshacer, y luego divida la tarea en partes pequeñas: solo se permite un archivo, una función o un tipo de reemplazo a la vez, y el plan de modificación y la diferencia deben generarse primero. Para reemplazos por lotes, primero realice una prueba en una copia o en una pequeña cantidad de archivos.

Relevancia para el artículo genérico sobre solución de problemas de MCP

Si el problema es que la conexión del servidor falla, la configuración no se carga, se informa el error de llamada a la herramienta o el cliente no encuentra MCP, primero consulte [Cómo solucionar problemas de falla de llamada a la herramienta MCP] (/es/2026/07/08/mcp-tool-call-failure-troubleshooting-faq/). Este artículo trata además la instalación específica, los permisos de archivos, el funcionamiento del terminal y las estrategias de edición diferencial de DesktopCommanderMCP; Los dos artículos se pueden usar en combinación para separar “no se puede conectar” y “cómo usarlo de manera segura después de conectarlo”.

Resumen

DesktopCommanderMCP es adecuado para poner la búsqueda de archivos, la edición diferencial y la verificación de terminales en el mismo flujo de trabajo en Claude Code o Codex. La forma correcta de usarlo es instalarlo primero en un directorio de proyecto restringido, primero realizar una búsqueda de solo lectura, luego revisar la diferencia y finalmente permitir la escritura y las pruebas; Los comandos a largo plazo, los directorios confidenciales y los montajes de Docker deben tener límites claros. Esto no solo puede maximizar la eficiencia de MCP, sino también evitar el riesgo de convertir los permisos locales en una automatización no revisable.

Almacén oficial: https://github.com/wonderwhy-er/DesktopCommanderMCP