Filesystem

Operaciones seguras de archivos con controles de acceso configurables

GitHub
90.5k

Documentación

Filesystem MCP Server

Servidor Node.js que implementa el Protocolo de Contexto de Modelo (MCP) para operaciones del sistema de archivos.

Publicado en npm como @modelcontextprotocol/server-filesystem.

Características

  • Leer/escribir archivos
  • Crear/listar/eliminar directorios
  • Mover archivos/directorios
  • Buscar archivos
  • Obtener metadatos de archivos
  • Control de acceso dinámico a directorios mediante Roots

Control de Acceso a Directorios

El servidor utiliza un sistema flexible de control de acceso a directorios. Los directorios pueden especificarse mediante argumentos de línea de comandos o dinámicamente mediante Roots.

Método 1: Argumentos de Línea de Comandos

Especifique los directorios permitidos al iniciar el servidor:

mcp-server-filesystem /path/to/dir1 /path/to/dir2

Método 2: MCP Roots (Recomendado)

Los clientes MCP que admiten Roots pueden actualizar dinámicamente los directorios permitidos.

Los Roots notificados por el Cliente al Servidor reemplazan completamente cualquier directorio permitido en el lado del servidor cuando se proporcionan.

Importante: Si el servidor se inicia sin argumentos de línea de comandos Y el cliente no admite el protocolo de roots (o proporciona roots vacíos), el servidor lanzará un error durante la inicialización.

Este es el método recomendado, ya que permite actualizaciones dinámicas de directorios en tiempo de ejecución mediante notificaciones roots/list_changed sin reiniciar el servidor, proporcionando una experiencia de integración más flexible y moderna.

Cómo Funciona

El control de acceso a directorios del servidor sigue este flujo:

  1. Inicio del Servidor

    • El servidor se inicia con los directorios de los argumentos de línea de comandos (si se proporcionan)
    • Si no se proporcionan argumentos, el servidor se inicia con directorios permitidos vacíos

  2. Conexión e Inicialización del Cliente

    • El cliente se conecta y envía la solicitud initialize con capacidades
    • El servidor verifica si el cliente admite el protocolo de roots (capabilities.roots)

  3. Manejo del Protocolo de Roots (si el cliente admite roots)

    • En la inicialización: El servidor solicita roots al cliente mediante roots/list
    • El cliente responde con sus roots configurados
    • El servidor reemplaza TODOS los directorios permitidos con los roots del cliente
    • En actualizaciones en tiempo de ejecución: El cliente puede enviar notifications/roots/list_changed
    • El servidor solicita roots actualizados y reemplaza nuevamente los directorios permitidos

  4. Comportamiento de Respaldo (si el cliente no admite roots)

    • El servidor continúa usando solo los directorios de línea de comandos
    • No es posible realizar actualizaciones dinámicas

  5. Control de Acceso

    • Todas las operaciones del sistema de archivos están restringidas a los directorios permitidos
    • Use la herramienta list_allowed_directories para ver los directorios actuales
    • El servidor requiere al menos UN directorio permitido para operar

Nota: El servidor solo permitirá operaciones dentro de los directorios especificados ya sea mediante args o mediante Roots.

API

Herramientas

  • read_text_file

    • Lee el contenido completo de un archivo como texto
    • Entradas:
      • path (string)
      • head (number, opcional): Primeras N líneas
      • tail (number, opcional): Últimas N líneas
    • Siempre trata el archivo como texto UTF-8 independientemente de la extensión
    • No se pueden especificar head y tail simultáneamente

  • read_media_file

    • Lee un archivo y lo devuelve como un bloque de contenido codificado en base64 con su tipo MIME
    • Entradas:
      • path (string)
    • Transmite el archivo y devuelve datos base64 con el tipo MIME correspondiente. Los archivos de imagen y audio se devuelven como contenido image/audio; cualquier otro tipo de archivo se devuelve como un resource incrustado (un bloque de contenido MCP válido para datos binarios arbitrarios)

  • read_multiple_files

    • Lee múltiples archivos simultáneamente
    • Entrada: paths (string[])
    • Las lecturas fallidas no detienen toda la operación

  • write_file

    • Crea un archivo nuevo o sobrescribe uno existente (tenga precaución con esto)
    • Entradas:
      • path (string): Ubicación del archivo
      • content (string): Contenido del archivo

  • edit_file

    • Realiza ediciones selectivas mediante coincidencia avanzada de patrones y formato
    • Características:
      • Coincidencia de contenido por líneas y multilínea
      • Normalización de espacios en blanco con preservación de la sangría
      • Múltiples ediciones simultáneas con posicionamiento correcto
      • Detección y preservación del estilo de sangría
      • Salida de diff estilo Git con contexto
      • Vista previa de cambios con modo de ejecución en seco
    • Entradas:
      • path (string): Archivo a editar
      • edits (array): Lista de operaciones de edición
        • oldText (string): Texto a buscar (puede ser una subcadena)
        • newText (string): Texto de reemplazo
      • dryRun (boolean): Vista previa de cambios sin aplicarlos (predeterminado: false)
    • Devuelve un diff detallado e información de coincidencia para ejecuciones en seco; de lo contrario, aplica los cambios
    • Mejor práctica: Use siempre dryRun primero para previsualizar los cambios antes de aplicarlos

  • create_directory

    • Crea un directorio nuevo o garantiza que exista
    • Entrada: path (string)
    • Crea directorios padres si es necesario
    • Tiene éxito silenciosamente si el directorio ya existe

  • list_directory

    • Lista el contenido del directorio con prefijos [FILE] o [DIR]
    • Entrada: path (string)

  • list_directory_with_sizes

    • Lista el contenido del directorio con prefijos [FILE] o [DIR], incluyendo tamaños de archivo
    • Entradas:
      • path (string): Ruta del directorio a listar
      • sortBy (string, opcional): Ordenar entradas por "name" o "size" (predeterminado: "name")
    • Devuelve un listado detallado con tamaños de archivo y estadísticas resumidas
    • Muestra archivos totales, directorios y tamaño combinado

  • move_file

    • Mueve o renombra archivos y directorios
    • Entradas:
      • source (string)
      • destination (string)
    • Falla si el destino ya existe

  • search_files

    • Busca recursivamente archivos/directorios que coincidan o no con patrones
    • Entradas:
      • path (string): Directorio de inicio
      • pattern (string): Patrón de búsqueda
      • excludePatterns (string[]): Excluir cualquier patrón.
    • Coincidencia de patrones estilo glob
    • Devuelve las rutas completas de las coincidencias

  • directory_tree

    • Obtiene la estructura de árbol JSON recursiva del contenido del directorio
    • Entradas:
      • path (string): Directorio de inicio
      • excludePatterns (string[]): Excluir cualquier patrón. Se admiten formatos glob.
    • Devuelve:
      • Arreglo JSON donde cada entrada contiene:
        • name (string): Nombre del archivo/directorio
        • type ('file'|'directory'): Tipo de entrada
        • children (array): Presente solo para directorios
          • Arreglo vacío para directorios vacíos
          • Omitido para archivos
    • La salida se formatea con sangría de 2 espacios para mayor legibilidad

  • get_file_info

    • Obtiene metadatos detallados del archivo/directorio
    • Entrada: path (string)
    • Devuelve:
      • Tamaño
      • Fecha de creación
      • Fecha de modificación
      • Fecha de acceso
      • Tipo (archivo/directorio)
      • Permisos

  • list_allowed_directories

    • Lista todos los directorios a los que el servidor tiene permitido acceder
    • No requiere entrada
    • Devuelve:
      • Directorios desde los cuales este servidor puede leer/escribir

Anotaciones de herramientas (pistas MCP)

Este servidor establece MCP ToolAnnotations en cada herramienta para que los clientes puedan:

  • Distinguir herramientas de solo lectura de herramientas con capacidad de escritura.
  • Comprender qué operaciones de escritura son idempotentes (seguras de reintentar con los mismos argumentos).
  • Resaltar operaciones que pueden ser destructivas (sobrescribir o mutar datos de forma intensiva).
  • Indicar que una herramienta no accede a un mundo abierto o externo (cada herramienta del sistema de archivos establece openWorldHint: false).

El mapeo para las herramientas del sistema de archivos es:

HerramientareadOnlyHintidempotentHintdestructiveHintNotas
read_text_filetrue––Solo lectura
read_media_filetrue––Solo lectura
read_multiple_filestrue––Solo lectura
list_directorytrue––Solo lectura
list_directory_with_sizestrue––Solo lectura
directory_treetrue––Solo lectura
search_filestrue––Solo lectura
get_file_infotrue––Solo lectura
list_allowed_directoriestrue––Solo lectura
create_directoryfalsetruefalseRecrear el mismo directorio es una operación nula
write_filefalsetruetrueSobrescribe archivos existentes
edit_filefalsefalsetrueReaplicar ediciones puede fallar o aplicarse doble
move_filefalsefalsetrueElimina el archivo de origen

Nota: idempotentHint y destructiveHint tienen significado solo cuando readOnlyHint es false, según lo definido por la especificación MCP. Cada herramienta también establece openWorldHint: false — este servidor solo accede al sistema de archivos local dentro de sus directorios permitidos, nunca a un mundo abierto o externo.

Uso con Claude Desktop

Agregue esto a su claude_desktop_config.json:

Nota: puede proporcionar directorios aislados (sandbox) al servidor montándolos en /projects. Agregar el indicador ro hará que el directorio sea de solo lectura para el servidor.

Docker

Nota: todos los directorios deben montarse en /projects de forma predeterminada.

{
  "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",
        "/projects"
      ]
    }
  }
}

NPX

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

En Windows, use cmd /c para iniciar npx:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

Uso con VS Code

Para una instalación rápida, haga clic en los botones de instalación a continuación...

Install with NPX in VS Code Install with NPX in VS Code Insiders

Install with Docker in VS Code Install with Docker in VS Code Insiders

Para instalación manual, puede configurar el servidor MCP usando uno de estos métodos:

Método 1: Configuración de Usuario (Recomendado) Agregue la configuración a su archivo de configuración MCP a nivel de usuario. Abra la Paleta de Comandos (Ctrl + Shift + P) y ejecute MCP: Open User Configuration. Esto abrirá su archivo mcp.json de usuario donde puede agregar la configuración del servidor.

Método 2: Configuración del Espacio de Trabajo Alternativamente, puede agregar la configuración a un archivo llamado .vscode/mcp.json en su espacio de trabajo. Esto le permitirá compartir la configuración con otros.

Para más detalles sobre la configuración de MCP en VS Code, consulte la documentación oficial de MCP para VS Code.

Puede proporcionar directorios aislados (sandbox) al servidor montándolos en /projects. Agregar el indicador ro hará que el directorio sea de solo lectura para el servidor.

Docker

Nota: todos los directorios deben montarse en /projects de forma predeterminada.

{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

En Windows, use:

{
  "servers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

Compilación

Compilación de Docker:

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

Licencia

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