Filesystem MCP Server for WSL

⚠️ INFORMACIÓN IMPORTANTE:
El servidor MCP del sistema de archivos original ya puede acceder a archivos WSL simplemente usando la ruta de red \\wsl.localhost\DistributionName como parámetro en la configuración.
Ejemplo:

{ "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "\\\\wsl.localhost\\Debian", "C:\\path\\to\\other\\allowed\\dir" ] } } }

Sin embargo, este proyecto ofrece una implementación alternativa específicamente optimizada para las distribuciones WSL de Linux .

Si bien el servidor oficial funciona recorriendo directorios de forma recursiva mediante el módulo fs de Node.js, esta implementación aprovecha los comandos nativos de Linux dentro de WSL (como find , grep , etc.), lo que hace que las operaciones de listado de archivos y búsqueda de contenido sean significativamente más rápidas .

Esto puede ser especialmente útil cuando se trabaja con árboles de directorios grandes o cuando el rendimiento de la búsqueda es crítico.

Si bien la ruta de red nativa puede ser más simple para muchos casos de uso, este proyecto sigue siendo una solución valiosa para los usuarios de WSL que buscan un mejor rendimiento o un control más personalizado sobre la lógica de indexación y búsqueda.

Servidor MCP del sistema de archivos para WSL

Servidor Node.js que implementa el Protocolo de contexto de modelo (MCP), diseñado específicamente para operaciones del sistema de archivos en el Subsistema de Windows para Linux (WSL).
Este proyecto es una bifurcación del servidor MCP del sistema de archivos original, pero completamente reinventado para entornos WSL.
A diferencia del proyecto original, que maneja operaciones de archivos genéricos, esta versión se centra exclusivamente en la interacción fluida entre distribuciones de Windows y Linux bajo WSL.
Ambos proyectos son compatibles y pueden ejecutarse en paralelo en el mismo sistema.

Características

• Acceda a cualquier distribución de WSL desde Windows
• Leer/escribir archivos en WSL desde el host de Windows
• Crear/enumerar/eliminar directorios en WSL
• Mover archivos/directorios a través del sistema de archivos WSL
• Buscar archivos dentro de WSL
• Obtener metadatos de archivos del sistema de archivos WSL
• Compatibilidad con múltiples distribuciones de WSL

Nota : El servidor sólo permite operaciones dentro de directorios especificados mediante args .

API

Recursos

• wsl -d <distrib> : Comando para operaciones en distribuciones WSL

Herramientas

• leer_archivo
  • Leer el contenido completo de un archivo desde WSL
  • Entrada: path (cadena)
  • Lee el contenido como texto UTF-8
• leer_múltiples_archivos
  • Leer varios archivos simultáneamente desde WSL
  • Entrada: paths (cadena[])
  • Las lecturas fallidas no detendrán toda la operación
• escribir_archivo
  • Crear o sobrescribir un archivo en WSL (usar con precaución)
  • Entradas:
    • path (cadena)
    • content (cadena)
• archivo_de_edición
  • Ediciones selectivas con coincidencia de patrones y formato avanzados
  • Entradas:
    • path (cadena)
    • edits (matriz de { oldText, newText } )
    • dryRun (booleano, opcional)
  • Características:
    • Coincidencia de múltiples líneas
    • Conservación de la sangría
    • Vista previa de diferencias al estilo Git
    • Modo de ejecución en seco no destructivo
• crear_directorio
  • Crear o garantizar la existencia de un directorio en WSL
  • Entrada: path (cadena)
• directorio_de_lista
  • Listar el contenido del directorio con prefijos [FILE] o [DIR]
  • Entrada: path (cadena)
• árbol de directorios
  • Vista de árbol JSON recursiva del contenido
  • Entrada: path (cadena)
• mover_archivo
  • Mover o renombrar archivos/directorios
  • Entradas:
    • source (cadena)
    • destination (cadena)
• archivos de búsqueda
  • Búsqueda recursiva por nombre
  • Entradas:
    • path (cadena)
    • pattern (cadena)
    • excludePatterns (cadena[], opcional)
• obtener_información_del_archivo
  • Metadatos detallados
  • Entrada: path (cadena)
  • Devuelve: tamaño, marcas de tiempo, tipo, permisos
• lista_de_directorios_permitidos
  • Enumera todos los directorios accesibles al servidor
• lista_wsl_distribuciones
  • Enumera las distribuciones disponibles y muestra la activa

Requisitos

• Subsistema de Windows para Linux (WSL) configurado correctamente
• Al menos una distribución de Linux instalada en WSL

Para los usuarios de Claude Desktop:
No se requiere instalación adicional: solo configure su claude_desktop_config.json .

Para desarrollo:

• Node.js (v14.0.0 o superior)
• TypeScript (incluido como dependencia de desarrollo)

Instalación de Node.js en Windows

1. Descargue el instalador desde nodejs.org
2. Ejecútalo y sigue las instrucciones.
3. Comprobar versiones:

Uso

Antes de ejecutar el servidor, debe compilar el proyecto TypeScript:

Ejecute el servidor especificando qué distribución de WSL utilizar (opcional) y qué directorios exponer:

Si no se especifica ninguna distribución, se utilizará la distribución WSL predeterminada.

Ejemplos

Acceder a la distribución Ubuntu-20.04:

Utilice la distribución predeterminada:

Uso con Claude Desktop

Agregue esto a su claude_desktop_config.json :

Opción 1: Utilizar una distribución WSL específica

Opción 2: Usar la distribución WSL predeterminada

En el segundo ejemplo, el sistema utilizará su distribución WSL predeterminada sin que usted necesite especificarla.

Diferencias con el proyecto original

Esta bifurcación adapta el servidor MCP del sistema de archivos original para que funcione con WSL mediante lo siguiente:

1. Reemplazo de llamadas directas al sistema de archivos Node.js con ejecuciones de comandos WSL
2. Agregar soporte para seleccionar distribuciones WSL específicas
3. Implementación de la traducción de rutas entre formatos de Windows y Linux
4. Mejora del manejo del contenido de archivos para compatibilidad entre plataformas
5. Agregar herramientas especializadas para la gestión de WSL

Licencia

Este proyecto es una bifurcación del servidor MCP del sistema de archivos original creado por el equipo del Protocolo de contexto de modelo.

Este servidor MCP para WSL está licenciado bajo la Licencia MIT, de acuerdo con la licencia del proyecto original. Esto significa que usted tiene libertad para usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia MIT. Para más detalles, consulte el archivo de LICENCIA en el repositorio del proyecto original.