Filesystem MCP Server

Servidor MCP de Filesystem

Un servidor MCP seguro y de un solo binario para operaciones de filesystem. Sin dependencias de runtime: descárgalo, configura los directorios permitidos y conéctalo a cualquier cliente MCP.

Probado exhaustivamente con Claude Desktop y Claude Code en flujos de trabajo de codificación reales, incluyendo edición de archivos, búsqueda en codebase, refactorización y operaciones por lotes de múltiples archivos.

¿Por qué este servidor?

• Un solo binario — no necesita Node.js, Python ni otro runtime. Descarga y ejecuta
• Probado con flujos de IA reales — probado en batalla con Claude Desktop y Claude Code para tareas de codificación diarias
• 18 herramientas — va más allá de lectura/escritura básica con búsqueda regex, reemplazo basado en patrones, inserción de código con autoindentación y operaciones por lotes
• Vista previa en seco — previsualiza los cambios antes de aplicarlos en herramientas de reemplazo e inserción
• Seguro por defecto — aislado en los directorios configurados con prevención de ataques de symlink y protección contra path traversal
• Mensajes de error detallados — cuando se deniega el acceso, los errores explican el motivo y sugieren soluciones

Instalación

Descargar un binario de release

Descarga el último binario para tu plataforma desde la página de Releases:

Plataforma	Binario
macOS (Apple Silicon)	filesystem-mcp-darwin-arm64
macOS (Intel)	filesystem-mcp-darwin-amd64
Linux (x86_64)	filesystem-mcp-linux-amd64
Linux (ARM64)	filesystem-mcp-linux-arm64
Windows	filesystem-mcp-windows-amd64.exe

Hazlo ejecutable (macOS/Linux):

chmod +x filesystem-mcp-darwin-arm64

Compilar desde el código fuente

go build -ldflags="-s -w" -o bin/filesystem-mcp ./cmd

Configuración

Establece los directorios permitidos usando la variable de entorno:

export MCP_ALLOWED_DIRS="/path1,/path2,/path with spaces/dir3"

Herramientas

Lectura

• read_file — Lee un solo archivo, con start_line/end_line opcionales para lecturas parciales
• read_multiple_files — Lee múltiples archivos simultáneamente en una sola llamada
• search_in_files — Búsqueda regex recursiva entre archivos. Devuelve rutas de archivo, números de línea y texto coincidente. Omite archivos binarios automáticamente. Parámetros: path, pattern, file_extensions, max_results, case_sensitive

Escritura

• write_file — Crea o sobrescribe un archivo. Crea automáticamente los directorios padre
• append_to_file — Añade contenido al final del archivo. Crea el archivo si no existe
• prepend_to_file — Añade contenido al inicio del archivo. Crea el archivo si no existe

Reemplazo de texto

Todas las herramientas de reemplazo admiten dry_run para previsualizar cambios sin aplicarlos.

• replace_in_file — Reemplaza ocurrencias exactas de una cadena en un archivo. Parámetros: path, search, replace, occurrence (0=todas), dry_run
• replace_in_file_regex — Reemplaza coincidencias de patrones regex con soporte de grupos de captura ($1, $2). Parámetros: path, pattern, replace, occurrence, case_sensitive, dry_run
• replace_in_files — Reemplaza una cadena por lotes en múltiples archivos. Valida todas las rutas antes de aplicar. Parámetros: paths, search, replace, dry_run

Inserción basada en regex

Todas las herramientas de inserción admiten dry_run y autoIndent (coincidir con la indentación circundante).

• insert_after_regex — Inserta contenido después de una coincidencia de patrón regex. Parámetros: path, pattern, content, occurrence (0=todas, predeterminado 1), autoIndent, dry_run
• insert_before_regex — Inserta contenido antes de una coincidencia de patrón regex. Mismos parámetros que arriba

Copia de líneas

• copy_lines — Copia un rango de líneas del archivo de origen al de destino directamente en disco (sin sobrecarga de contexto). Parámetros: source_path, destination_path, start_line, end_line, append

Operaciones de directorio

• list_directory — Lista el contenido del directorio con filtrado por patrón, tipo de archivo, profundidad de recursión, archivos ocultos y metadatos. Parámetros: path, pattern, file_type, recursive, max_depth, max_results, include_hidden, include_metadata
• create_directory — Crea directorio y padres (idempotente)
• list_allowed_directories — Muestra los directorios accesibles

Gestión de archivos

• move_file — Mueve o renombra archivos y directorios
• get_file_info — Obtiene metadatos del archivo (tamaño, permisos, tiempo de modificación)

Uso con Claude Desktop

Añade a claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/filesystem-mcp-darwin-arm64",
      "env": {
        "MCP_ALLOWED_DIRS": "/path1,/path2,/path with spaces/dir3"
      }
    }
  }
}

Seguridad

El servidor implementa seguridad en profundidad para prevenir el acceso no autorizado a archivos.

Validación de rutas

• Resolución de enlaces simbólicos: todas las rutas se resuelven a forma canónica mediante filepath.EvalSymlinks() antes de la validación
• Prevención de path traversal: bloquea intentos de escape con ../
• Protección de coincidencia de prefijos: valida con separadores de ruta para prevenir que /allowed coincida con /allowed_attacker

Manejo de enlaces simbólicos

• Se permiten symlinks dentro de los directorios permitidos si su destino también está dentro de los directorios permitidos
• Se bloquean los symlinks que apuntan fuera de los directorios permitidos
• Se rechazan los symlinks rotos
• Los directorios permitidos pueden ser enlaces simbólicos (resueltos durante la inicialización)

Seguridad en operaciones de escritura

• Se valida la cadena de directorios padre para la creación de nuevos archivos
• La resolución y validación de rutas ocurren atómicamente

Registro de seguridad

• Todos los intentos de acceso bloqueados se registran con el prefijo SECURITY:
• Los registros incluyen tanto la ruta solicitada como su resolución canónica

Mejores prácticas

• Configura MCP_ALLOWED_DIRS con los directorios mínimos necesarios
• Usa rutas absolutas para los directorios permitidos
• Monitorea los registros en busca de mensajes SECURITY:

Licencia

Licencia MIT