Secure MCP Filesystem Server

Un servidor MCP seguro para acceder al sistema de archivos local dentro de directorios predefinidos.

Documentación

Secure MCP Filesystem Server

Un servidor seguro del Protocolo de Contexto de Modelo (MCP) que proporciona acceso al sistema de archivos dentro de directorios predefinidos

:bookmark: Acerca de

MCP Filesystem Server proporciona acceso seguro al sistema de archivos para modelos de IA a través del Protocolo de Contexto de Modelo. Aplica una validación estricta de rutas y solo permite el acceso a directorios predefinidos.

:computer: Tecnologías

TypeScript
Node.js
MCP SDK
Zod
Docker
pnpm

:wrench: Herramientas

:package: Instalación

:heavy_check_mark: Requisitos previos

El siguiente software debe estar instalado:

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

Usando el 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

Usando Docker Compose

  # Create a data directory
  $ mkdir -p data

  # Start the server
  $ docker-compose up -d

:gear: Uso

Usando con Claude Desktop

Claude Desktop se puede configurar para usar este servidor MCP para el acceso al sistema de archivos. Agrega lo siguiente a tu claude_desktop_config.json:

Usando la instalación local (recomendado)

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

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

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

Usando 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 montarse en /projects de forma predeterminada. Agregar la bandera ro hará que el directorio sea 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 MCP Filesystem Server proporciona estas herramientas:

Operaciones del sistema de archivos

read_file: Lee el contenido de un archivo
read_multiple_files: Lee varios archivos a la vez
write_file: Crea o sobrescribe un archivo
edit_file: Realiza ediciones precisas con vista previa de diff
create_directory: Crea directorios de forma recursiva
list_directory: Lista el contenido del directorio
directory_tree: Obtiene una vista de árbol recursiva
move_file: Mueve o renombra archivos
search_files: Encuentra archivos que coincidan con patrones
get_file_info: Obtiene metadatos del archivo
list_allowed_directories: Muestra los directorios accesibles

Operaciones del sistema y red

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 APIs externas (próximamente en v1.2.0)

Usando la herramienta curl_request (próximamente en v1.2.0)

La herramienta curl_request te permitirá realizar solicitudes HTTP a APIs 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}',
})

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

:sparkles: Características

Características principales

Acceso seguro: La validación estricta de rutas evita el acceso no autorizado
Operaciones de archivos: Lee, escribe, edita y mueve archivos
Operaciones de directorios: Crea, lista, obtiene vistas de árbol y busca directorios
Acceso a metadatos: Ver información de archivos y directorios
Ejecución de comandos: Ejecuta comandos del sistema de forma segura con validación estricta
Soporte Docker: Implementación fácil con Docker y Docker Compose

Nuevas características en v0.3.0

Registro estructurado: Registro detallado con diferentes niveles (debug, info, warn, error)
Métricas de rendimiento: Realiza un seguimiento de conteos de operaciones, errores y tiempos de ejecución
Gestión de configuración: Soporte para archivos de configuración JSON
Caché de rutas: Rendimiento mejorado para rutas de acceso frecuente
Manejo de errores mejorado: Tipos de error especializados con información estructurada
Validación de tamaño de archivo: Evita cargar archivos excesivamente grandes
Mejoras de CLI: Comando de ayuda, información de versión y generación de configuración

Opciones de configuración

Puedes crear un archivo de configuración usando:

$ 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


Gabriel Maia

Licencia

MIT License