Servidor del sistema de archivos MCP

Un potente servidor de Protocolo de Contexto de Modelo (MCP) para operaciones de sistemas de archivos, optimizado para la interacción inteligente con archivos y sistemas de archivos de gran tamaño. Proporciona acceso seguro a archivos y directorios con gestión inteligente del contexto para maximizar la eficiencia al trabajar con grandes volúmenes de datos.

¿Por qué MCP-Filesystem?

Gestión inteligente del contexto : trabaje de manera eficiente con archivos y sistemas de archivos grandes
- Lectura parcial para centrarse solo en el contenido relevante
- Control de contexto preciso para encontrar exactamente lo que necesita
- Resultados de búsqueda eficientes en tokens con paginación
- Operaciones con múltiples archivos para reducir la sobrecarga de solicitudes
Operaciones de archivos inteligentes :
- Lectura orientada a líneas con ventanas de contexto configurables
- Edición avanzada con verificación de contenido para evitar conflictos
- Capacidades de búsqueda de grano fino que superan el grep estándar
- Referencias de línea relativas para una manipulación precisa de archivos

Características principales

Acceso seguro a archivos : solo permite operaciones dentro de directorios explícitamente permitidos
Operaciones integrales : conjunto completo de capacidades del sistema de archivos
- Operaciones estándar (leer, escribir, enumerar, mover, eliminar)
- Operaciones mejoradas (visualización de árboles, búsqueda de duplicados, etc.)
- Búsqueda avanzada con integración de grep (usa ripgrep cuando está disponible)
  - Control de contexto (como las opciones -A/-B/-C de grep)
  - Paginación de resultados para conjuntos de resultados grandes
- Operaciones dirigidas a líneas con verificación de contenido y números de línea relativos
Rendimiento optimizado :
- Maneja eficientemente archivos y directorios grandes
- Integración de Ripgrep para búsquedas ultrarrápidas
- Operaciones dirigidas a líneas para evitar cargar archivos completos
Pruebas integrales : más de 75 pruebas con un enfoque basado en el comportamiento
Multiplataforma : funciona en Windows, macOS y Linux

Guía de inicio rápido

1. Clonar y configurar

Primero, instala uv si aún no lo has hecho:

# Install uv using the official installer
curl -fsSL https://raw.githubusercontent.com/astral-sh/uv/main/install.sh | bash

# Or with pipx
pipx install uv

Luego clona el repositorio e instala las dependencias:

# Clone the repository
git clone https://github.com/safurrier/mcp-filesystem.git
cd mcp-filesystem

# Install dependencies with uv
uv pip sync requirements.txt requirements-dev.txt

2. Obtener rutas absolutas

Necesitará rutas absolutas tanto para la ubicación del repositorio como para cualquier directorio al que desee acceder:

# Get the absolute path to the repository
REPO_PATH=$(pwd)
echo "Repository path: $REPO_PATH"

# Get absolute paths to directories you want to access
realpath ~/Documents
realpath ~/Downloads
# Or on systems without realpath:
echo "$(cd ~/Documents && pwd)"

3. Configurar Claude Desktop

Abra el archivo de configuración de Claude Desktop:

En macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
En Windows: %APPDATA%/Claude/claude_desktop_config.json

Agregue la siguiente configuración (sustituya sus rutas actuales):

{
  "mcpServers": {
    "mcp-filesystem": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-filesystem",
        "run",
        "run_server.py",
        "/absolute/path/to/dir1",
        "/absolute/path/to/dir2"
      ]
    }
  }
}

Importante : Todas las rutas deben ser absolutas (rutas completas desde el directorio raíz). Use realpath o pwd para asegurarse de tener las rutas absolutas correctas.

4. Reinicie Claude Desktop

Después de guardar su configuración, reinicie Claude Desktop para que los cambios surtan efecto.

Instalación

Uso

Ver registros del servidor

Puede supervisar los registros del servidor desde Claude Desktop con:

# On macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-filesystem.log

# On Windows (PowerShell)
Get-Content -Path "$env:APPDATA\Claude\Logs\mcp-server-mcp-filesystem.log" -Tail 20 -Wait

Esto es particularmente útil para depurar problemas o ver exactamente lo que Claude está solicitando.

Ejecución del servidor

Ejecute el servidor con acceso a directorios específicos:

# Using uv (recommended)
uv run run_server.py /path/to/dir1 /path/to/dir2

# Or using standard Python
python run_server.py /path/to/dir1 /path/to/dir2

# Example with actual paths
uv run run_server.py /Users/username/Documents /Users/username/Downloads

Opciones

--transport o -t : Protocolo de transporte (stdio o sse, predeterminado: stdio)
--port o -p : Puerto para transporte SSE (predeterminado: 8000)
--debug o -d : Habilitar el registro de depuración
--version o -v : Mostrar información de la versión

Uso con MCP Inspector

Para realizar pruebas y depuraciones interactivas con el Inspector MCP:

# Basic usage
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory

# With SSE transport
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --transport sse --port 8080

# With debug output
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --debug

Este servidor se ha desarrollado con el SDK de FastMCP para una mejor adaptación a las mejores prácticas actuales de MCP. Utiliza un sistema eficiente de almacenamiento en caché de componentes y un patrón de decorador directo.

Integración de escritorio de Claude

Edite el archivo de configuración de Claude Desktop para integrar MCP-Filesystem:

Ubicación del archivo de configuración:

En macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
En Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-filesystem": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-filesystem/repo",
        "run",
        "run_server.py"
      ]
    }
  }
}

Para permitir el acceso a directorios específicos, agréguelos como argumentos adicionales:

{
  "mcpServers": {
    "mcp-filesystem": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-filesystem/repo",
        "run",
        "run_server.py",
        "/Users/yourusername/Projects",
        "/Users/yourusername/Documents"
      ]
    }
  }
}

Nota: El indicador --directory es importante, ya que indica a uv dónde encontrar el repositorio que contiene run_server.py. Reemplace /path/to/mcp-filesystem/repo con la ruta real donde clonó el repositorio en su sistema.

Desarrollo

Ejecución de pruebas

# Run all tests
uv run -m pytest tests/

# Run specific test file
uv run -m pytest tests/test_operations_unit.py

# Run with coverage
uv run -m pytest tests/ --cov=mcp_filesystem --cov-report=term-missing

Estilo y calidad del código

# Format code
uv run -m ruff format mcp_filesystem

# Lint code
uv run -m ruff check --fix mcp_filesystem

# Type check
uv run -m mypy mcp_filesystem

# Run all checks
uv run -m ruff format mcp_filesystem && \
uv run -m ruff check --fix mcp_filesystem && \
uv run -m mypy mcp_filesystem && \
uv run -m pytest tests --cov=mcp_filesystem

Herramientas disponibles

Operaciones básicas con archivos

read_file : Lee el contenido completo de un archivo
read_multiple_files : Leer varios archivos simultáneamente
write_file : Crea un nuevo archivo o sobrescribe un archivo existente
create_directory : Crea un nuevo directorio o asegúrate de que exista un directorio
list_directory : Obtenga una lista detallada de archivos y directorios
move_file : Mover o renombrar archivos y directorios
get_file_info : recupera metadatos detallados sobre un archivo o directorio
list_allowed_directories : enumera los directorios a los que el servidor tiene permiso de acceso

Operaciones dirigidas a la línea

read_file_lines : lee rangos de líneas específicos con parámetros de desplazamiento/límite
edit_file_at_line : Realice ediciones precisas con verificación de contenido y números de línea relativos
- Soporte para verificación de contenido para evitar editar contenido obsoleto
- Números de línea relativos para facilitar la edición regional
- Múltiples acciones de edición (reemplazar, insertar antes, insertar después, eliminar)
head_file : Lee las primeras N líneas de un archivo de texto
tail_file : lee las últimas N líneas de un archivo de texto

Búsqueda avanzada

grep_files : busca patrones en archivos con opciones potentes
- Integración de Ripgrep para mejorar el rendimiento (con respaldo de Python)
- Control de contexto de grano fino (como las opciones -A/-B/-C de grep)
- Paginación de resultados para resultados de búsqueda grandes
- Compatibilidad con expresiones regulares con distinción entre mayúsculas y minúsculas y opciones de palabras completas
search_files : Busca archivos que coincidan con patrones de búsqueda de contenido
directory_tree : Obtener una vista de árbol recursiva de archivos y directorios

Análisis e informes

calculate_directory_size : Calcula el tamaño total de un directorio
find_duplicate_files : Encuentra archivos duplicados comparando el contenido
compare_files : Compara dos archivos de texto y muestra las diferencias
find_large_files : busca archivos más grandes que un tamaño especificado
find_empty_directories : Encuentra directorios vacíos

Ejemplos de uso

Leyendo líneas de archivo

Tool: read_file_lines
Arguments: {
  "path": "/path/to/file.txt",
  "offset": 99,        # 0-based indexing (line 100)
  "limit": 51,         # Read 51 lines
  "encoding": "utf-8"  # Optional encoding
}

Búsqueda de contenido con Grep

Tool: grep_files
Arguments: {
  "path": "/path/to/search",
  "pattern": "function\\s+\\w+\\(",
  "is_regex": true,
  "context_before": 2,       # Show 2 lines before each match (like grep -B)
  "context_after": 5,        # Show 5 lines after each match (like grep -A)
  "include_patterns": ["*.js", "*.ts"],
  "results_offset": 0,       # Start from the first match
  "results_limit": 20        # Show at most 20 matches
}

Edición orientada a líneas

Tool: edit_file_at_line
Arguments: {
  "path": "/path/to/file.txt",
  "line_edits": [
    {
      "line_number": 15,
      "action": "replace",
      "content": "This is the new content for line 15\n",
      "expected_content": "Original content of line 15\n" # Verify content before editing
    },
    {
      "line_number": 20,
      "action": "delete"
    }
  ],
  "offset": 0,                           # Start considering lines from this offset
  "relative_line_numbers": false,        # Whether line numbers are relative to offset
  "abort_on_verification_failure": true, # Stop on verification failure
  "dry_run": true                        # Preview changes without applying
}

Encontrar archivos duplicados

Tool: find_duplicate_files
Arguments: {
  "path": "/path/to/search",
  "recursive": true,
  "min_size": 1024,
  "format": "text"
}

Flujo de trabajo eficiente para archivos y sistemas de archivos grandes

MCP-Filesystem está diseñado para la interacción inteligente con archivos grandes y sistemas de archivos complejos:

Descubrimiento de contexto inteligente
- Utilice grep_files para encontrar exactamente lo que necesita con un control de contexto preciso
- El control detallado sobre las líneas de contexto antes y después de las coincidencias evita el desperdicio de tokens
- Paginar grandes conjuntos de resultados de manera eficiente sin sobrecargar los límites de tokens
- La integración de Ripgrep maneja sistemas de archivos masivos con millones de archivos y líneas
Lectura dirigida
- Examine solo las secciones relevantes con read_file_lines usando offset/limit
- Indexación basada en cero con parámetros de desplazamiento/límite simples para una recuperación precisa de contenido
- Controle exactamente cuántas líneas leer para maximizar la eficiencia del token
- Leer varios archivos simultáneamente para reducir los viajes de ida y vuelta
Edición precisa
- Realice ediciones específicas con edit_file_at_line con verificación de contenido
- Verifique que el contenido no haya cambiado antes de editarlo para evitar conflictos.
- Utilice números de línea relativos para la edición regional en archivos complejos
- Múltiples acciones de edición en una sola operación para cambios complejos
- Capacidad de ejecución en seco para obtener una vista previa de los cambios antes de aplicarlos
Análisis avanzado
- Utilice herramientas especializadas como find_duplicate_files y compare_files
- Genere árboles de directorios con directory_tree para una navegación rápida
- Identifique áreas problemáticas con find_large_files y find_empty_directories

Este flujo de trabajo es especialmente valioso para herramientas basadas en IA que necesitan trabajar con archivos y sistemas de archivos de gran tamaño. Por ejemplo, Claude y otros asistentes de IA avanzados pueden aprovechar estas capacidades para navegar eficientemente por bases de código, analizar archivos de registro o trabajar con grandes conjuntos de datos de texto, manteniendo la eficiencia de los tokens.

Ventajas sobre los servidores MCP del sistema de archivos estándar

A diferencia de los servidores MCP de sistemas de archivos básicos, MCP-Filesystem ofrece:

Eficiencia del token
- Las operaciones inteligentes dirigidas a líneas evitan cargar archivos completos en contexto
- Los controles de paginación para resultados grandes evitan el desbordamiento de contexto
- Grep preciso con controles de contexto (no solo búsquedas en archivos completos)
- La lectura de múltiples archivos reduce las solicitudes de ida y vuelta
Edición inteligente
- Verificación de contenido para evitar conflictos de edición
- Ediciones orientadas a líneas que no requieren el archivo completo
- Compatibilidad con números de línea relativos para una edición regional más sencilla
- Capacidad de ejecución en seco para obtener una vista previa de los cambios antes de aplicarlos
Búsqueda avanzada
- Integración de Ripgrep para un rendimiento masivo del sistema de archivos
- Resultados según el contexto (no solo coincidencias)
- Control detallado sobre lo que se devuelve
- Búsqueda de archivos basada en patrones con soporte de exclusión
Utilidades adicionales
- Comparación y deduplicación de archivos
- Cálculo y análisis del tamaño del directorio
- Identificación de directorio vacío
- Visualización de directorios basada en árboles
Enfoque de seguridad
- Validación de ruta robusta y sandboxing
- Protección contra ataques de cruce de ruta
- Validación y seguridad de enlaces simbólicos
- Informe detallado de errores sin exposición sensible

Problemas y limitaciones conocidos

Resolución de rutas : Utilice siempre rutas absolutas para obtener resultados más consistentes. Las rutas relativas podrían interpretarse en relación con el directorio de trabajo del servidor, en lugar de los directorios permitidos.
Rendimiento : en el caso de directorios grandes, operaciones como find_duplicate_files o búsqueda recursiva pueden tardar un tiempo considerable en completarse.
Manejo de permisos : El servidor opera con los mismos permisos que el usuario que lo ejecuta. Asegúrese de que el servidor tenga los permisos adecuados para los directorios a los que necesita acceder.

Seguridad

El servidor aplica una validación de ruta estricta para evitar el acceso fuera de los directorios permitidos:

Sólo permite operaciones dentro de directorios explícitamente permitidos
Proporciona protección contra ataques de cruce de ruta
Valida los enlaces simbólicos para garantizar que no apunten fuera de los directorios permitidos
Devuelve mensajes de error significativos sin exponer información confidencial

Consideraciones de rendimiento

Para obtener el mejor rendimiento con la funcionalidad grep:

Instalar ripgrep ( rg )
El servidor utiliza automáticamente ripgrep si está disponible, con una alternativa de Python

Licencia

Licencia MIT

MCP Filesystem Server

Integrations