File System MCP Server

Un servidor para la gestión integral de archivos y directorios en el sistema de archivos local.

GitHub
2
Prueba este MCPPatrocinado

Documentación

File System MCP Server

Un potente servidor de gestión del sistema de archivos construido con FastMCP que proporciona un conjunto completo de herramientas para operaciones con archivos y directorios. Este servidor le permite realizar diversas operaciones del sistema de archivos a través de una API estructurada, lo que lo hace ideal para la automatización y la integración con otros sistemas.

Soporte de plataforma

El servidor está diseñado para funcionar en diferentes sistemas operativos, pero con distintos niveles de funcionalidad:

Windows

  • Soporte completo de funciones
  • Listado de unidades
  • Acceso a carpetas especiales
  • Manejo de rutas específico de Windows
  • Información detallada del sistema

macOS/Linux

  • Operaciones básicas de archivos
  • Operaciones con directorios
  • Búsqueda de archivos y metadatos
  • Información básica del sistema
  • Nota: Algunas funciones específicas de Windows no están disponibles

Implementación futura

Soporte planificado para macOS

  • Manejo nativo de rutas para macOS
  • Recuperación de información del sistema específica de macOS
  • Integración con las funciones del sistema de archivos de macOS
  • Soporte para atributos de archivo específicos de macOS
  • Implementación de utilidades específicas de macOS (similar a windows_utils.py)

Soporte planificado para Linux

  • Manejo nativo de rutas para Linux
  • Recuperación de información del sistema específica de Linux
  • Integración con las funciones del sistema de archivos de Linux
  • Soporte para permisos y atributos de archivos de Linux
  • Implementación de utilidades específicas de Linux

Mejoras multiplataforma

  • Sistema unificado de manejo de rutas
  • Detección de unidades independiente de la plataforma
  • API de información del sistema coherente
  • Atributos de archivo estandarizados entre plataformas
  • Monitoreo de eventos del sistema de archivos multiplataforma
  • Sistema universal de recopilación de archivos

Cronograma

  • Fase 1: Mejoras básicas de compatibilidad multiplataforma
  • Fase 2: Implementaciones de funciones específicas de la plataforma
  • Fase 3: Funciones avanzadas multiplataforma
  • Fase 4: Optimizaciones y refinamientos de rendimiento

Funciones

Operaciones con archivos

  • Copiar archivos con soporte de copia de seguridad
  • Mover archivos con soporte de copia de seguridad
  • Eliminar archivos con comprobaciones de seguridad
  • Leer contenido de archivos
  • Escribir contenido en archivos
  • Obtener información del archivo (tamaño, hora de creación, hora de modificación)
  • Buscar archivos por patrón de nombre
  • Crear colecciones de archivos para organizar archivos relacionados

Operaciones con directorios

  • Listar contenido de directorios
  • Crear directorios
  • Eliminar directorios
  • Listar directorios de forma recursiva (estructura tipo árbol)
  • Buscar directorios por patrón de nombre

Información del sistema

  • Obtener información del sistema (SO, CPU, memoria, uso de disco)
  • Obtener información del disco (espacio total, espacio usado, espacio libre)
  • Obtener información del directorio (número de archivos, tamaño total)

Estructura del proyecto

file-system-mcp-server/
├── fs_server.py            # Main server implementation
├── windows_utils.py        # Windows-specific utilities (Windows only)
├── requirements.txt        # Project dependencies
└── test_prompts_example.md # Example test prompts

Almacenamiento de colecciones

Las colecciones se pueden almacenar en cualquier directorio especificado por el usuario. Si no se especifica una ubicación de almacenamiento, las colecciones se guardarán en una ubicación predeterminada dentro del directorio data/collections del proyecto.

Ejemplo de uso:

# Store in default location
create_collection("my_collection", ["file1.txt", "file2.txt"])

# Store in custom location
create_collection("my_collection", ["file1.txt", "file2.txt"], storage_path="/path/to/store")

Dependencias

Dependencias requeridas

  • FastMCP
  • Pydantic
  • pywin32 (solo Windows)
  • WMI (solo Windows)

Para instalar las dependencias:

pip install -r requirements.txt

Configuración

  1. Clone el repositorio:
git clone https://github.com/calebmwelsh/file-system-mcp-server.git
cd file-system-mcp-server
  1. Cree y active un entorno virtual:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Instale las dependencias:
pip install -r requirements.txt

Uso

Para obtener instrucciones detalladas de configuración de MCP en diferentes entornos de desarrollo (Claude, Cursor, Windsurf), visite: Guía de configuración de MCP

Integración con Claude

Para integrar el servidor MCP del sistema de archivos con Claude, agregue lo siguiente a su archivo claude_desktop_config.json:

{
  "mcpServers": {
    "file-system": {
      "command": "/absolute/path/to/python",
      "args": [
        "/absolute/path/to/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

Encontrar su ruta de Python

Para encontrar la ruta de su ejecutable de Python, use el siguiente comando:

Windows (PowerShell):

(Get-Command python).Source

Windows (Símbolo del sistema/Terminal):

where python

Linux/macOS (Terminal):

which python

Reemplace /absolute/path/to/python con el resultado del comando apropiado anterior.

Ejemplo de configuración

Para Windows, su configuración podría verse así:

{
  "mcpServers": {
    "file-system": {
      "command": "C:\\Users\\YourUsername\\AppData\\Local\\Programs\\Python\\Python39\\python.exe",
      "args": [
        "C:\\Users\\YourUsername\\Documents/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

Para macOS/Linux:

{
  "mcpServers": {
    "file-system": {
      "command": "/usr/local/bin/python3",
      "args": [
        "/Users/YourUsername/Documents/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

Después de agregar la configuración:

  1. Guarde el archivo claude_desktop_config.json
  2. Reinicie Claude
  3. Ahora puede usar las herramientas del sistema de archivos pidiéndole a Claude que realice operaciones con archivos

Herramientas disponibles

Operaciones con archivos

  • copy_file: Copiar un archivo con copia de seguridad opcional
  • move_file: Mover un archivo con copia de seguridad opcional
  • delete_file: Eliminar un archivo con comprobaciones de seguridad
  • read_file: Leer el contenido de un archivo
  • write_file: Escribir contenido en un archivo
  • get_file_info: Obtener información detallada del archivo
  • search_files: Buscar archivos por patrón de nombre
  • create_collection: Crear una colección de archivos

Operaciones con directorios

  • list_directory: Listar el contenido de un directorio
  • create_directory: Crear un nuevo directorio
  • delete_directory: Eliminar un directorio
  • list_directory_recursively: Mostrar la estructura del directorio en formato de árbol
  • search_directories: Buscar directorios por patrón de nombre

Información del sistema

  • get_system_info: Obtener información del sistema
  • get_disk_info: Obtener información de uso del disco
  • get_directory_info: Obtener estadísticas del directorio

Problemas conocidos

Actualmente, las siguientes funciones presentan problemas y pueden no funcionar como se espera:

  1. Función de eliminar archivo

    • La función delete_file puede fallar al eliminar archivos correctamente en algunos casos
    • Se recomienda verificar la eliminación del archivo manualmente o usar métodos alternativos cuando sea crítico
    • El problema está bajo investigación y se corregirá en una futura actualización

  2. Función de listar unidades

    • La función list_drives puede no detectar ni mostrar correctamente todas las unidades disponibles
    • Algunas unidades pueden faltar en la lista o mostrar información incorrecta
    • Esta es una limitación conocida y se abordará en futuras actualizaciones

  3. Limitaciones específicas de la plataforma

    • Las funciones específicas de Windows no están disponibles en macOS/Linux
    • Algunos manejos de rutas pueden diferir entre plataformas
    • La recuperación de información del sistema varía según la plataforma

Manejo de errores

El servidor incluye un manejo integral de errores para:

  • Rutas de archivo no válidas
  • Archivo/directorio no encontrado
  • Problemas de permisos
  • Limitaciones de espacio en disco
  • Operaciones no válidas
  • Errores específicos de la plataforma

Seguridad

  • Todas las operaciones con archivos incluyen validación de rutas
  • Se crean copias de seguridad antes de operaciones destructivas
  • El acceso a la información del sistema está restringido a operaciones seguras
  • Las operaciones con archivos se realizan con un manejo de errores adecuado

Contribución

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Realice sus cambios
  4. Envíe la rama
  5. Cree una solicitud de extracción (Pull Request)

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulte el archivo LICENSE para obtener más detalles.

Agradecimientos

  • Construido con FastMCP
  • Utiliza Pydantic para la validación de datos
  • Inspirado en herramientas modernas de gestión del sistema de archivos