Filesystem MCP Server for WSL

Un servidor de sistema de archivos para el Subsistema de Windows para Linux (WSL), que utiliza comandos nativos para operaciones de archivos más rápidas.

GitHub

Prueba este MCPPatrocinado

Documentación

⚠️ INFORMACIÓN IMPORTANTE:
El Filesystem MCP Server original ya puede acceder a archivos de 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 distribuciones Linux de WSL.

Mientras que el servidor oficial funciona recorriendo directorios de forma recursiva usando el módulo fs de Node.js, esta implementación aprovecha 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 búsqueda es crítico.

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

Filesystem MCP Server para WSL

Servidor Node.js que implementa el Protocolo de Contexto de Modelo (MCP), diseñado específicamente para operaciones de sistema de archivos en el Subsistema de Windows para Linux (WSL).
Este proyecto es un fork del Filesystem MCP Server original, pero completamente rediseñado para entornos WSL.
A diferencia del proyecto original, que maneja operaciones genéricas de archivos, esta versión se centra exclusivamente en la interacción fluida entre Windows y las distribuciones de Linux bajo WSL.
Ambos proyectos son compatibles y pueden ejecutarse en paralelo en el mismo sistema.

Características

Accede a cualquier distribución de WSL desde Windows
Lee/escribe archivos en WSL desde el host de Windows
Crea/lista/elimina directorios en WSL
Mueve archivos/directorios dentro del sistema de archivos de WSL
Busca archivos dentro de WSL
Obtiene metadatos de archivos del sistema de archivos de WSL
Soporte para múltiples distribuciones de WSL

Nota: El servidor solo permite operaciones dentro de los directorios especificados mediante args.

API

Recursos

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

Herramientas

read_file
- Lee el contenido completo de un archivo desde WSL
- Entrada: path (cadena)
- Lee el contenido como texto UTF-8
read_file_by_parts
- Lee archivos grandes en partes de aproximadamente 95,000 caracteres
- Entradas:
  - path (cadena)
  - part_number (entero positivo: 1, 2, 3, etc.)
- Características:
  - La parte 1 comienza desde el inicio del archivo
  - Las partes subsiguientes se alinean con los límites de línea (ajuste máximo de 300 caracteres)
  - Devuelve un error con el tamaño real del archivo si la parte solicitada no existe
  - Útil para archivos demasiado grandes para leerlos en una sola operación
read_multiple_files
- Lee múltiples archivos simultáneamente desde WSL
- Entrada: paths (cadena[])
- Las lecturas fallidas no detienen toda la operación
write_file
- Crea o sobrescribe un archivo en WSL (usar con precaución)
- Entradas:
  - path (cadena)
  - content (cadena)
edit_file
- Ediciones selectivas con coincidencia de patrones avanzada y formato
- Entradas:
  - path (cadena)
  - edits (matriz de { oldText, newText })
  - dryRun (booleano, opcional)
- Características:
  - Coincidencia multilínea
  - Preservación de sangría
  - Vista previa de diff estilo Git
  - Modo de prueba no destructivo
create_directory
- Crea o asegura la existencia de un directorio en WSL
- Entrada: path (cadena)
list_directory
- Lista el contenido del directorio con prefijos [FILE] o [DIR]
- Entrada: path (cadena)
directory_tree
- Vista de árbol JSON recursiva del contenido
- Entrada: path (cadena)
move_file
- Mueve o renombra archivos/directorios
- Entradas:
  - source (cadena)
  - destination (cadena)
search_files
- Busca recursivamente por nombre
- Entradas:
  - path (cadena)
  - pattern (cadena)
  - excludePatterns (cadena[], opcional)
search_in_files
- Busca patrones de texto dentro de archivos de forma recursiva
- Entradas:
  - path (cadena) - directorio raíz para buscar
  - pattern (cadena) - texto o patrón regex para encontrar
  - caseInsensitive (booleano, opcional) - búsqueda sin distinción de mayúsculas/minúsculas
  - isRegex (booleano, opcional) - tratar el patrón como regex
  - includePatterns (cadena[], opcional) - patrones de archivo a incluir (p. ej., *.js)
  - excludePatterns (cadena[], opcional) - patrones de archivo a excluir
  - maxResults (número, opcional, predeterminado: 1000) - máximo de resultados a devolver
  - contextLines (número, opcional, predeterminado: 0) - líneas de contexto antes/después
- Características:
  - Maneja todos los caracteres especiales (apóstrofes, comillas, $, barras invertidas)
  - Soporta búsquedas de texto plano y expresiones regulares
  - Muestra líneas coincidentes con rutas de archivo y números de línea
  - Excluye automáticamente los directorios .git, node_modules, .svn, .hg
  - Puede mostrar líneas de contexto alrededor de las coincidencias
get_file_info
- Metadatos detallados
- Entrada: path (cadena)
- Devuelve: tamaño, marcas de tiempo, tipo, permisos
list_allowed_directories
- Lista todos los directorios accesibles para el servidor
list_wsl_distributions
- Lista 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 usuarios de Claude Desktop:
No se requiere instalación adicional — solo configura tu claude_desktop_config.json.

Paquete NPM:
El paquete está disponible en npm: mcp-server-wsl-filesystem

Para desarrollo:

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

Instalando Node.js en Windows

Descarga el instalador desde nodejs.org
Ejecútalo y sigue las instrucciones
Verifica las versiones:

node --version
npm --version

Uso

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

npm install
npm run build

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

node dist/index.js [--distro=distribution_name] <allowed_directory> [additional_directories...]

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

Ejemplos

Accede a la distribución Ubuntu-20.04:

node dist/index.js --distro=Ubuntu-20.04 /home/user/documents

Usa la distribución predeterminada:

node dist/index.js /home/user/documents

Uso con Claude Desktop

Agrega esto a tu claude_desktop_config.json:

Opción 1: Usando una distribución específica de WSL

{
  "mcpServers": {
    "wsl-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-wsl-filesystem",
        "--distro=Ubuntu-20.04",
        "/home/user/documents"
      ]
    }
  }
}

Opción 2: Usando la distribución predeterminada de WSL

{
  "mcpServers": {
    "wsl-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-wsl-filesystem",
        "/home/user/documents"
      ]
    }
  }
}

En el segundo ejemplo, el sistema usará tu distribución predeterminada de WSL sin necesidad de especificarla.

Diferencias con el proyecto original

Este fork adapta el Filesystem MCP Server original para trabajar con WSL mediante:

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

Licencia

Este proyecto es un fork del Filesystem MCP Server original creado por el equipo del Protocolo de Contexto de Modelo.

Este servidor MCP para WSL está licenciado bajo la Licencia MIT, siguiendo la licencia del proyecto original. Esto significa que eres libre de usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia MIT. Para más detalles, consulta el archivo LICENSE en el repositorio del proyecto original.