Servidor MCP del sistema de archivos

Servidor Node.js que implementa el Protocolo de Contexto de Modelo (MCP) para operaciones del sistema de archivos con controles de permisos integrales y funcionalidad mejorada.

Características

Controles de permisos granulares (solo lectura, acceso completo o permisos de operación específicos)
Operaciones de archivos seguras dentro de directorios permitidos
Operaciones con archivos:
- Leer/escribir/modificar archivos
- Crear/enumerar/eliminar directorios
- Mover archivos/directorios
- Buscar archivos por nombre o extensión
- Obtener metadatos de archivos
Operaciones de directorio:
- Vista de árbol de las estructuras de directorios
- Operaciones recursivas con patrones de exclusión
Funciones de utilidad:
- Conversión de XML a JSON
- Múltiples operaciones de archivo en una sola llamada
- Edición avanzada de archivos con coincidencia de patrones
Características de seguridad:
- Control de enlace simbólico
- Validación de ruta
- Operaciones en espacio aislado

Nota : El servidor solo permitirá operaciones dentro de directorios especificados mediante args y de acuerdo con los permisos configurados.

API

Recursos

file://system : Interfaz de operaciones del sistema de archivos

Herramientas

leer_archivo
- Leer el contenido completo de un archivo
- Entrada: path (cadena)
- Lee el contenido completo del archivo con codificación UTF-8
leer_múltiples_archivos
- Leer varios archivos simultáneamente
- Entrada: paths (cadena[])
- Las lecturas fallidas no detendrán toda la operación
crear_archivo
- Crear un nuevo archivo con contenido
- Entradas:
  - path (cadena): Ubicación del archivo
  - content (cadena): contenido del archivo
- Falla si el archivo ya existe
- Requiere permiso create
modificar_archivo
- Modificar un archivo existente con contenido nuevo
- Entradas:
  - path (cadena): Ubicación del archivo
  - content (cadena): Nuevo contenido del archivo
- Falla si el archivo no existe
- Requiere permiso edit
archivo_de_edición
- Realice ediciones selectivas utilizando coincidencia de patrones y formato
- Características:
  - Coincidencia de contenido basada en líneas y multilíneas
  - Normalización de espacios en blanco con conservación de sangría
  - Múltiples ediciones simultáneas con posicionamiento correcto
  - Detección y conservación del estilo de sangría
  - Salida de diferencias al estilo Git con contexto
  - Vista previa de los cambios con el modo de ejecución en seco
- Entradas:
  - path (cadena): Archivo a editar
  - edits (matriz): Lista de operaciones de edición
    - oldText (cadena): Texto a buscar (coincidencia exacta)
    - newText (cadena): Texto con el que reemplazar
  - dryRun (booleano): Vista previa de los cambios sin aplicarlos (valor predeterminado: falso)
- Devuelve una diferencia detallada para ejecuciones en seco; de lo contrario, aplica los cambios.
- Requiere permiso edit
- Práctica recomendada: utilice siempre dryRun primero para obtener una vista previa de los cambios
crear_directorio
- Crear un nuevo directorio o asegurarse de que exista
- Entrada: path (cadena)
- Crea directorios principales si es necesario
- Tiene éxito silenciosamente si el directorio existe
- Requiere permiso create
directorio_de_lista
- Listar el contenido del directorio con prefijos [FILE] o [DIR]
- Entrada: path (cadena)
- Devuelve una lista detallada de archivos y directorios.
árbol de directorios
- Obtener una vista de árbol recursiva de la estructura del directorio
- Entrada: path (cadena)
- Devuelve la estructura JSON con archivos y directorios
- Cada entrada incluye nombre, tipo y elementos secundarios (para directorios)
mover_archivo
- Mover o renombrar archivos y directorios
- Entradas:
  - source (cadena): Ruta de origen
  - destination (cadena): Ruta de destino
- Falla si el destino existe
- Funciona tanto para archivos como para directorios.
- Requiere permiso move
eliminar_archivo
- Eliminar un archivo
- Entrada: path (cadena)
- Falla si el archivo no existe
- Requiere permiso delete
eliminar_directorio
- Eliminar un directorio
- Entradas:
  - path (cadena): Directorio a eliminar
  - recursive (booleano): si se debe eliminar el contenido (valor predeterminado: falso)
- Falla si el directorio no está vacío y el recursivo es falso
- Requiere permiso delete
archivos de búsqueda
- Buscar archivos/directorios de forma recursiva
- Entradas:
  - path (cadena): Directorio de inicio
  - pattern (cadena): Buscar patrón
  - excludePatterns (string[]): Excluye patrones (formato glob compatible)
- Coincidencia sin distinción entre mayúsculas y minúsculas
- Devuelve rutas completas a las coincidencias
buscar_archivos_por_extensión
- Encuentra todos los archivos con extensión específica
- Entradas:
  - path (cadena): Directorio de inicio
  - extension (cadena): Extensión del archivo a buscar
  - excludePatterns (string[]): Patrones de exclusión opcionales
- Coincidencia de extensiones sin distinción entre mayúsculas y minúsculas
- Devuelve rutas completas a los archivos coincidentes
obtener_información_del_archivo
- Obtener metadatos detallados de archivos/directorios
- Entrada: path (cadena)
- Devoluciones:
  - Tamaño
  - Tiempo de creación
  - Hora modificada
  - Tiempo de acceso
  - Tipo (archivo/directorio)
  - Permisos
obtener_permisos
- Obtener los permisos actuales del servidor
- No se requiere entrada
- Devoluciones:
  - Banderas de permisos (solo lectura, acceso completo, crear, editar, mover, eliminar)
  - Estado de seguimiento del enlace simbólico
  - Número de directorios permitidos
lista_de_directorios_permitidos
- Enumere todos los directorios a los que el servidor tiene permiso de acceder
- No se requiere entrada
- Devuelve una matriz de rutas de directorio permitidas
xml_a_json
- Convertir archivo XML a formato JSON
- Entradas:
  - xmlPath (cadena): archivo XML de origen
  - jsonPath (cadena): archivo JSON de destino
  - options (objeto): configuraciones opcionales
    - ignoreAttributes (booleano): omite atributos XML (valor predeterminado: falso)
    - preserveOrder (booleano): Mantener el orden de la propiedad (valor predeterminado: verdadero)
    - format (booleano): JSON de impresión bonita (predeterminado: verdadero)
    - indentSize (número): sangría JSON (predeterminado: 2)
- Requiere permiso read para el archivo XML
- Requiere permiso para create o edit archivos JSON
cadena xml_a_json
- Convertir archivo XML a cadena JSON
- Entradas:
  - xmlPath (cadena): archivo XML de origen
  - options (objeto): configuraciones opcionales
    - ignoreAttributes (booleano): omite atributos XML (valor predeterminado: falso)
    - preserveOrder (booleano): Mantener el orden de la propiedad (valor predeterminado: verdadero)
- Requiere permiso read para el archivo XML
- Devuelve la representación de cadena JSON
consulta_xml
- Consultar archivo XML mediante expresiones XPath
- Entradas:
  - path (cadena): Ruta al archivo XML
  - query (cadena, opcional): consulta XPath a ejecutar
  - structureOnly (booleano, opcional): Devuelve solo la estructura de la etiqueta
  - maxBytes (número, opcional): Máximo de bytes a leer (predeterminado: 1 MB)
  - includeAttributes (booleano, opcional): incluye información del atributo (valor predeterminado: verdadero)
- Ejemplos de XPath:
  - Obtener todos los elementos: //tagname
  - Obtener elementos con atributo específico: //tagname[@attr="value"]
  - Obtener el contenido del texto: //tagname/text()
- Uso eficiente de la memoria para archivos XML grandes
- Devuelve la representación JSON de los resultados o la estructura de la consulta.
estructura_xml
- Analizar la estructura XML sin leer el archivo completo
- Entradas:
  - path (cadena): Ruta al archivo XML
  - depth (número, opcional): Qué tan profundo analizar (predeterminado: 2)
  - includeAttributes (booleano, opcional): incluye análisis de atributos
  - maxBytes (número, opcional): Máximo de bytes a leer (predeterminado: 1 MB)
- Devuelve información estadística sobre elementos, atributos y estructura.
- Útil para comprender archivos XML grandes antes de realizar un análisis detallado

Permisos y seguridad

El servidor implementa un modelo de seguridad integral con controles de permisos granulares:

Control de acceso al directorio

Las operaciones están estrictamente limitadas a los directorios especificados durante el inicio a través de args
Todas las operaciones (incluidos los destinos de enlaces simbólicos) deben permanecer dentro de los directorios permitidos
La validación de ruta garantiza que no se pueda atravesar ningún directorio ni acceder a él fuera de las rutas permitidas

Banderas de permiso

--readonly : Aplica el modo de solo lectura, anulando todos los demás indicadores de permisos
--full-access : Habilita todas las operaciones (crear, editar, mover, eliminar)
Banderas de permisos individuales (requieren habilitación explícita a menos que se configure --full-access):
- --allow-create : Permitir la creación de nuevos archivos y directorios
- --allow-edit : Permitir la modificación de archivos existentes
- --allow-move : Permitir mover/renombrar archivos y directorios
- --allow-delete : Permitir la eliminación de archivos y directorios

Comportamiento predeterminado : Si no se especifican indicadores de permiso, el servidor se ejecuta en modo de solo lectura. Para habilitar cualquier operación de escritura, debe usar los indicadores --full-access o --allow-* .

Manejo de enlaces simbólicos

De forma predeterminada, se siguen los enlaces simbólicos (tanto el enlace como el destino deben estar en directorios permitidos)
--no-follow-symlinks : Deshabilita el seguimiento de enlaces simbólicos (las operaciones actúan sobre el enlace en sí)

Uso con Claude Desktop y Cursor

Agregue la configuración adecuada a claude_desktop_config.json (para Claude Desktop) o .cursor/mcp.json (para Cursor):

Configuración del cursor

En .cursor/mcp.json :

{
  "mcpServers": {
    "my-filesystem": {
      "command": "node",
      "args": [
        "/path/to/mcp-filesystem/dist/index.js",
        "~/path/to/allowed/directory",
        "--full-access"
      ]
    }
  }
}

Configuración de Docker

Para Claude Desktop con Docker:

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "mcp/filesystem",
        "--readonly",                    // For read-only access
        "--no-follow-symlinks",         // Optional: prevent symlink following
        "/projects"
      ]
    }
  }
}

Configuración NPX

Para Claude Desktop o Cursor con NPX:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "--full-access",                // For full read/write access
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

Ejemplos de banderas de permiso

Puede configurar el servidor con varias combinaciones de permisos:

"args": [
  "/path/to/mcp-filesystem/dist/index.js",
  "~/path/to/allowed/directory",
  "--readonly"                         // Read-only mode
]

"args": [
  "/path/to/mcp-filesystem/dist/index.js",
  "~/path/to/allowed/directory",
  "--full-access",                    // Full read/write access
  "--no-follow-symlinks"              // Don't follow symlinks
]

"args": [
  "/path/to/mcp-filesystem/dist/index.js",
  "~/path/to/allowed/directory",
  "--allow-create",                   // Selective permissions
  "--allow-edit"                      // Only allow creation and editing
]

Nota: --readonly tiene prioridad sobre todos los demás indicadores de permisos, y --full-access habilita todas las operaciones a menos que se especifique --readonly .

Múltiples directorios y permisos

Al especificar varios directorios, los indicadores de permiso se aplican globalmente a todos los directorios:

"args": [
  "/path/to/mcp-filesystem/dist/index.js",
  "~/first/directory",                // Both directories have the same
  "~/second/directory",               // permission settings (read-only)
  "--readonly"
]

Si necesita diferentes niveles de permisos para distintos directorios, cree múltiples configuraciones de servidor:

{
  "mcpServers": {
    "readonly-filesystem": {
      "command": "node",
      "args": [
        "/path/to/mcp-filesystem/dist/index.js",
        "~/sensitive/directory",
        "--readonly"
      ]
    },
    "writeable-filesystem": {
      "command": "node",
      "args": [
        "/path/to/mcp-filesystem/dist/index.js",
        "~/sandbox/directory",
        "--full-access"
      ]
    }
  }
}

Ejemplos de línea de comandos

Acceso de solo lectura:

npx -y @modelcontextprotocol/server-filesystem --readonly /path/to/dir

Acceso completo:

npx -y @modelcontextprotocol/server-filesystem --full-access /path/to/dir

Permisos específicos:

npx -y @modelcontextprotocol/server-filesystem --allow-create --allow-edit /path/to/dir

No hay ningún enlace simbólico a continuación:

npx -y @modelcontextprotocol/server-filesystem --full-access --no-follow-symlinks /path/to/dir

Construir

Compilación de Docker:

docker build -t mcp/filesystem -f src/filesystem/Dockerfile .

Licencia

Este servidor MCP cuenta con la licencia MIT. Esto significa que puede usar, modificar y distribuir el software libremente, 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.

Filesystem MCP Server