Remote File Server

remote-file-server-mcp

Dale a cualquier asistente de IA acceso de lectura a tus recursos compartidos de archivos SMB/CIFS — de forma segura, en minutos.

---

¿Qué es esto?

Un servidor MCP (Model Context Protocol) que conecta Claude Desktop (o cualquier cliente MCP) con tu recurso compartido de red SMB/CIFS — servidores de archivos Windows, unidades NAS, recursos Samba, cualquier cosa que use SMB.

Pídele a Claude que lea informes, busque en hojas de cálculo o resuma documentos que viven en tu red — sin mover un solo archivo, sin pegar credenciales en un chat ni otorgar acceso de escritura.

flowchart LR
    A("🤖 Claude Desktop\nor any MCP client"):::client
    B("🔌 file-server-mcp\n<i>this server</i>"):::server
    C("🗄️ SMB File Server\nWindows · NAS · Samba"):::storage

    A -- "MCP / stdio" --> B
    B -- "SMB 445 · encrypted" --> C

    classDef client  fill:#7c3aed,color:#fff,stroke:none
    classDef server  fill:#2563eb,color:#fff,stroke:none
    classDef storage fill:#0f766e,color:#fff,stroke:none

---

Características de un vistazo

Solo lectura por diseño	El servidor no expone ninguna operación de escritura — tus archivos están seguros
Las credenciales permanecen locales	Se pasan como variables de entorno, nunca aparecen en llamadas de herramientas ni en el historial del chat
Cifrado y firma SMB	La firma de paquetes y el cifrado están activados por defecto; establece SMB_ENCRYPT=false para desactivar solo el cifrado
Bloqueo de traversal de rutas	Los segmentos .. se rechazan antes de realizar cualquier llamada SMB
Lista de denegación de archivos sensibles	.env, *.key, *.pem, id_rsa, almacenes de claves y más nunca se listan ni se leen
Registro de auditoría	Cada llamada de herramienta se escribe como una entrada JSON (operación, ruta, resultado y metadatos específicos de la herramienta) — nunca el contenido de los archivos
Análisis de Office y PDF	Los archivos de Excel, Word, PowerPoint y PDF se convierten en texto legible — requiere los extras opcionales [docs]
Lista de permitidos de subdirectorios	Limita el servidor solo a los directorios que el modelo realmente necesita

---

Herramientas

Herramienta	Argumentos	Descripción
list_files	path (opcional)	Lista archivos y directorios. Ruta vacía = raíz del recurso compartido. Devuelve JSON.
read_file	path	Devuelve el contenido de texto. Los archivos demasiado grandes devuelven una vista previa o un error grave. Los archivos de Office/PDF se analizan.
get_file_info	path	Devuelve metadatos (tamaño, tipo, marcas de tiempo) sin leer el archivo.
search_files	pattern, path (opcional), max_depth (opcional)	Búsqueda con glob (p. ej. *.csv). Recursivo hasta max_depth (por defecto 5, máximo 10), devuelve hasta 200 coincidencias.

Todas las rutas son relativas a la raíz del recurso compartido — p. ej. reports/2024/q1.xlsx.

---

Inicio rápido

Opción A — instalación con pip

pip install -e /path/to/remote-file-server

Luego usa "command": "file-server-mcp" en la configuración de tu cliente MCP.

Opción B — uv (sin instalación necesaria)

uv run --directory /path/to/remote-file-server file-server-mcp

Opción C — ejecutar desde el código fuente

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python server.py

Opción D — Docker

docker build -t file-server-mcp .

Consulta Dockerfile para el uso en tiempo de ejecución.

---

Configuración del cliente MCP

Añade una entrada bajo mcpServers en tu archivo de configuración del cliente.

uv (ejecutar desde el código fuente, sin instalación previa):

{
  "mcpServers": {
    "file-server": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/remote-file-server", "file-server-mcp"],
      "env": {
        "SMB_HOST": "192.168.1.100",
        "SMB_SHARE": "my_share",
        "SMB_USERNAME": "my_user",
        "SMB_PASSWORD": "my_password"
      }
    }
  }
}

pip/uv pip (punto de entrada de script de consola):

{
  "mcpServers": {
    "file-server": {
      "command": "file-server-mcp",
      "env": {
        "SMB_HOST": "192.168.1.100",
        "SMB_SHARE": "my_share",
        "SMB_USERNAME": "my_user",
        "SMB_PASSWORD": "my_password",
        "SMB_PORT": "445",
        "ALLOWED_PATHS": "reports,finance",
        "AUDIT_LOG_PATH": "/var/log/file-server-mcp/audit.jsonl"
      }
    }
  }
}

Nota de seguridad: Este archivo de configuración contiene credenciales — restringe sus permisos (chmod 600 en macOS/Linux).

Reinicia tu cliente MCP después de guardar.

Conexión a múltiples servidores

{
  "mcpServers": {
    "file-server-prod": {
      "command": "file-server-mcp",
      "env": { "SMB_HOST": "10.0.0.10", "SMB_SHARE": "Production", "...": "..." }
    },
    "file-server-dev": {
      "command": "file-server-mcp",
      "env": { "SMB_HOST": "10.0.0.20", "SMB_SHARE": "Development", "...": "..." }
    }
  }
}

---

Variables de entorno

Variable	Obligatoria	Por defecto	Descripción
SMB_HOST	Sí	—	Dirección IP o nombre de host del servidor SMB
SMB_SHARE	Sí	—	Nombre del recurso compartido en el servidor
SMB_USERNAME	Sí	—	Nombre de usuario para la autenticación SMB
SMB_PASSWORD	Sí	—	Contraseña para la autenticación SMB
SMB_PORT	No	445	Puerto SMB
SMB_ENCRYPT	No	true	Establece false para desactivar el cifrado SMB (no recomendado)
SMB_TIMEOUT	No	30	Segundos antes de que una conexión u operación SMB expire
MAX_FILE_SIZE_MB	No	10	Tamaño máximo de archivo en MB que read_file leerá
READ_PREVIEW_LINES	No	100	Líneas a devolver para archivos demasiado grandes. Establece 0 para generar un error grave en su lugar
ALLOWED_PATHS	No	—	Lista de permitidos de subdirectorios separados por comas, p. ej. reports,finance/2024
AUDIT_LOG_PATH	No	stderr	Ruta de archivo para los registros de auditoría JSON. Vuelve a stderr si no se establece

---

Seguridad

• La firma de paquetes SMB es obligatoria en todas las conexiones.
• El traversal de rutas está bloqueado — los segmentos .. se rechazan antes de cualquier llamada SMB.
• La lista de denegación de archivos sensibles cubre .env, *.key, *.pem, *.bak, id_rsa, *.pfx, *.p12, *.token, .netrc, .htpasswd, archivos de almacenes de claves y más. Para producción, combínalo con ALLOWED_PATHS para restringir el acceso solo a los directorios que el modelo necesita.
• El límite de tamaño de archivo evita leer archivos que desbordarían la ventana de contexto.
• El registro de auditoría registra cada llamada de herramienta en JSON (operación, ruta, resultado, metadatos específicos de la herramienta) — nunca el contenido de los archivos.
• Los mensajes de error están saneados — los nombres de host internos, las rutas UNC y las credenciales nunca se exponen al cliente.

---

Requisitos

• Python 3.11+
• Acceso de red al servidor SMB (puerto 445 por defecto)
• Credenciales SMB con permisos de lectura en el recurso compartido