Filesystem MCP Server

Servidor Node.js que implementa Model Context Protocol (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 a través de 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 soportan Roots pueden actualizar dinámicamente los directorios permitidos.

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

Importante: Si el servidor se inicia sin argumentos de línea de comandos Y el cliente no soporta el protocolo 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 de directorio 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 inicia con los directorios de los argumentos de línea de comandos (si se proporcionan)

   • Si no se proporcionan argumentos, el servidor inicia con directorios permitidos vacíos

2. Conexión e Inicialización del Cliente

   • El cliente se conecta y envía una solicitud initialize con capacidades

   • El servidor verifica si el cliente soporta el protocolo roots (capabilities.roots)

3. Manejo del Protocolo Roots (si el cliente soporta 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 los roots actualizados y reemplaza nuevamente los directorios permitidos

4. Comportamiento Alternativo (si el cliente no soporta 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

  • Leer el contenido completo de un archivo como texto

  • Entradas:

    • path (cadena)

    • head (número, opcional): Primeras N líneas

    • tail (número, 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

  • Leer un archivo y devolverlo como un bloque de contenido codificado en base64 con su tipo MIME

  • Entradas:

    • path (cadena)

  • Transmite el archivo y devuelve datos en 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

  • Leer múltiples archivos simultáneamente

  • Entrada: paths (cadena[])

  • Las lecturas fallidas no detendrán toda la operación

• write_file

  • Crear un archivo nuevo o sobrescribir uno existente (tenga cuidado con esto)

  • Entradas:

    • path (cadena): Ubicación del archivo

    • content (cadena): Contenido del archivo

• edit_file

  • Realizar ediciones selectivas utilizando 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 sangría

    • Múltiples ediciones simultáneas con posicionamiento correcto

    • Detección y preservación del estilo de sangría

    • Salida diff estilo Git con contexto

    • Vista previa de cambios con modo de ejecución en seco

  • Entradas:

    • path (cadena): Archivo a editar

    • edits (arreglo): Lista de operaciones de edición

      • oldText (cadena): Texto a buscar (puede ser una subcadena)

      • newText (cadena): Texto con el que reemplazar

    • dryRun (booleano): Vista previa de cambios sin aplicar (predeterminado: false)

  • Devuelve información detallada de diff y coincidencia para ejecuciones en seco; de lo contrario, aplica los cambios

  • Mejor práctica: Siempre use dryRun primero para previsualizar los cambios antes de aplicarlos

• create_directory

  • Crear un nuevo directorio o asegurarse de que exista

  • Entrada: path (cadena)

  • Crea los directorios padre si es necesario

  • Se ejecuta silenciosamente si el directorio existe

• list_directory

  • Listar el contenido del directorio con prefijos [FILE] o [DIR]

  • Entrada: path (cadena)

• list_directory_with_sizes

  • Listar el contenido del directorio con prefijos [FILE] o [DIR], incluyendo tamaños de archivo

  • Entradas:

    • path (cadena): Ruta del directorio a listar

    • sortBy (cadena, opcional): Ordenar entradas por "name" o "size" (predeterminado: "name")

  • Devuelve un listado detallado con tamaños de archivo y estadísticas resumidas

  • Muestra total de archivos, directorios y tamaño combinado

• move_file

  • Mover o renombrar archivos y directorios

  • Entradas:

    • source (cadena)

    • destination (cadena)

  • Fallo si el destino existe

• search_files

  • Búsqueda recursiva de archivos/directorios que coincidan o no coincidan con patrones

  • Entradas:

    • path (cadena): Directorio de inicio

    • pattern (cadena): Patrón de búsqueda

    • excludePatterns (cadena[]): Excluir cualquier patrón.

  • Coincidencia de patrones estilo glob

  • Devuelve rutas completas a las coincidencias

• directory_tree

  • Obtener estructura JSON recursiva del árbol de contenidos del directorio

  • Entradas:

    • path (cadena): Directorio de inicio

    • excludePatterns (cadena[]): Excluir cualquier patrón. Se soportan formatos glob.

  • Devuelve:

    • Arreglo JSON donde cada entrada contiene:

      • name (cadena): Nombre del archivo/directorio

      • type ('file'|'directory'): Tipo de entrada

      • children (arreglo): Presente solo para directorios

        • Arreglo vacío para directorios vacíos

        • Omitido para archivos

  • La salida está formateada con sangría de 2 espacios para legibilidad

• get_file_info

  • Obtener metadatos detallados de archivos/directorios

  • Entrada: path (cadena)

  • Devuelve:

    • Tamaño

    • Hora de creación

    • Hora de modificación

    • Hora de acceso

    • Tipo (archivo/directorio)

    • Permisos

• list_allowed_directories

  • Listar todos los directorios a los que el servidor tiene permitido acceder

  • No requiere entrada

  • Devuelve:

    • Directorios desde los que este servidor puede leer/escribir

Anotaciones de herramientas (pistas MCP)

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

• Distinguir las herramientas de solo lectura de las 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).

• Señalar 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:

Nota: idempotentHint y destructiveHint solo tienen sentido 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 al servidor montándolos en /projects. Agregar la bandera 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...

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 VS Code MCP.

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

Docker

Nota: todos los directorios deben montarse en /projects por defecto.

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

Build

Docker build:

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.