Servidor del sistema de archivos MCP

: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.

:computer: Tecnologías

Mecanografiado
Node.js
Kit de desarrollo de software de MCP
Zod
Estibador
pnpm

:wrench: Herramientas

: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


Gabriel Maia

Licencia

Licencia MIT

MCP Filesystem Server

Integrations

:bookmark: Acerca de

:computer: Tecnologías

:wrench: Herramientas

:paquete: Instalación

:heavy_check_mark: Requisitos previos

:arrow_down: Clonando el repositorio

:arrow_forward: Ejecutando la aplicación

Desarrollo local

Uso del paquete NPM

Usando Docker

Uso de Docker Compose

:gear: Uso

Uso con Claude Desktop

Uso de la instalación local (recomendado)

Uso de NPX

Usando Docker

Herramientas disponibles

Operaciones del sistema de archivos

Operaciones de sistemas y redes

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

:sparkles: Características

Características principales

Nuevas funciones en la versión v0.3.0

Opciones de configuración

:writing_hand: Autor

Licencia