: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
:wrench: Herramientas
:paquete: Instalación
:heavy_check_mark: Requisitos previos
Se debe instalar el siguiente software:
: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