MCP Filesystem Server

:bookmark: Acerca de

El Servidor de Sistema de Archivos MCP proporciona acceso seguro al sistema de archivos para modelos de IA mediante el Protocolo de Contexto de Modelo. Aplica una validación estricta de rutas y solo permite el acceso a directorios predefinidos.

Related MCP server: MCP Filesystem Server

:computer: Tecnologías

• Mecanografiado

• Node.js

• Kit de desarrollo de software de MCP

• Zod

• Estibador

• pnpm

:wrench: Herramientas

• Código de Visual Studio

• ESLint

• Más bonita

• Vitest

• Docker Compose

:paquete: Instalación

:heavy_check_mark: Requisitos previos

Se debe instalar el siguiente software:

• Node.js (>=18.0.0)

• Git

• pnpm (>=8.0.0)

• Docker (opcional)

• Docker Compose (opcional)

:arrow_down: Clonando el repositorio

  $ git clone https://github.com/gabrielmaialva33/mcp-filesystem.git
  $ cd mcp-filesystem

:arrow_forward: Ejecutando la aplicación

Desarrollo local

  # Install dependencies
  $ pnpm install

  # Build the application
  $ pnpm build

  # Run the server (specify directory to allow access to)
  $ pnpm start /path/to/allowed/directory

  # Or use configuration file
  $ pnpm start --config=config.json

Uso del paquete NPM

  # Install globally
  $ npm install -g @gabrielmaialva33/mcp-filesystem

  # Run the server
  $ mcp-filesystem /path/to/allowed/directory

  # Or use with npx (no installation needed)
  $ npx @gabrielmaialva33/mcp-filesystem /path/to/allowed/directory

  # Create a sample configuration file
  $ npx @gabrielmaialva33/mcp-filesystem --create-config=config.json

Usando Docker

  # Build the Docker image
  $ docker build -t gabrielmaialva33/mcp-filesystem .

  # Run using Docker
  $ docker run -i --rm -v /path/to/data:/data:ro gabrielmaialva33/mcp-filesystem /data

  # Use with config file
  $ docker run -i --rm -v /path/to/config.json:/app/config.json -v /path/to/data:/data gabrielmaialva33/mcp-filesystem --config=/app/config.json

Uso de Docker Compose

  # Create a data directory
  $ mkdir -p data

  # Start the server
  $ docker-compose up -d

:gear: Uso

Uso con Claude Desktop

Claude Desktop se puede configurar para usar este servidor MCP para acceder al sistema de archivos. Agregue lo siguiente a su claude_desktop_config.json :

Uso de la instalación local (recomendado)

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-filesystem",
      "args": [
        "/Users/gabrielmaia/Documents",
        "/Users/gabrielmaia/Desktop",
        "/Users/gabrielmaia/Downloads"
      ]
    }
  }
}

Asegúrese de que el ejecutable esté disponible globalmente:

# Make the binary executable
chmod +x /Users/gabrielmaia/.nvm/versions/node/v22.14.0/bin/mcp-filesystem

Uso de NPX

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

Usando Docker

Nota: Al usar Docker, todos los directorios deben estar montados en /projects por defecto. Al añadir el indicador ro , el directorio será de solo lectura.

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

Herramientas disponibles

El servidor del sistema de archivos MCP proporciona estas herramientas:

Operaciones del sistema de archivos

• read_file : Leer el contenido de un archivo

• read_multiple_files : Leer varios archivos a la vez

• write_file : Crea o sobrescribe un archivo

• edit_file : Realice ediciones precisas con vista previa de diferencias

• create_directory : Crea directorios recursivamente

• list_directory : Lista el contenido del directorio

• directory_tree : Obtener una vista de árbol recursiva

• move_file : Mover o renombrar archivos

• search_files : Encuentra archivos que coincidan con patrones

• get_file_info : Obtener metadatos del archivo

• list_allowed_directories : Ver directorios accesibles

Operaciones de sistemas y redes

• get_metrics : Ver métricas de rendimiento del servidor (v0.3.0+)

• execute_command : Ejecuta comandos del sistema de forma segura (v0.3.1+)

• curl_request : Ejecuta solicitudes HTTP a API externas (próximamente en v1.2.0)

Uso de la herramienta curl_request (próximamente en la versión 1.2.0)

La herramienta curl_request le permitirá realizar solicitudes HTTP a API externas:

// Example: Making a GET request with authentication
curl_request({
  url: 'https://api.example.com/data',
  method: 'GET',
  headers: {
    Authorization: 'Bearer your_token_here',
  },
})

// Example: POST request with JSON data
curl_request({
  url: 'https://api.example.com/create',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  data: '{"name":"Example","value":123}',
})

Consulte el archivo docs/curl-tool-examples.md para obtener ejemplos más detallados.

:sparkles: Características

Características principales

• Acceso seguro : la validación estricta de la ruta evita el acceso no autorizado

• Operaciones de archivos : leer, escribir, editar y mover archivos

• Operaciones de directorio : crear, enumerar, obtener vistas de árbol y buscar directorios

• Acceso a metadatos : ver información de archivos y directorios

• Ejecución de comandos : ejecute comandos del sistema de forma segura con una validación estricta

• Compatibilidad con Docker : Implementación sencilla con Docker y Docker Compose

Nuevas funciones en la versión v0.3.0

• Registro estructurado : registro detallado con diferentes niveles (depuración, información, advertencia, error)

• Métricas de rendimiento : Realice un seguimiento de los recuentos de operaciones, errores y tiempos de ejecución

• Gestión de la configuración : Compatibilidad con archivos de configuración JSON

• Almacenamiento en caché de rutas : rendimiento mejorado para rutas a las que se accede con frecuencia

• Manejo de errores mejorado : tipos de errores especializados con información estructurada

• Validación del tamaño de archivo : evita cargar archivos excesivamente grandes

• Mejoras de la CLI : comando de ayuda, información de la versión y generación de configuración

Opciones de configuración

Puede crear un archivo de configuración utilizando:

$ mcp-filesystem --create-config=config.json

Ejemplo de configuración:

{
  "allowedDirectories": ["/path/to/allowed/dir1", "/path/to/allowed/dir2"],
  "logLevel": "info",
  "logFile": "/path/to/logs/mcp-filesystem.log",
  "serverName": "secure-filesystem-server",
  "serverVersion": "0.3.0",
  "cache": {
    "enabled": true,
    "maxSize": 1000,
    "ttlMs": 60000
  },
  "metrics": {
    "enabled": true,
    "reportIntervalMs": 60000
  },
  "security": {
    "maxFileSize": 10485760,
    "allowSymlinks": true,
    "validateRealPath": true
  }
}

:writing_hand: Autor

Licencia

Licencia MIT