photo-enhance-mcp

Servidor MCP local para editar y mejorar fotos con IA, más un visor web antes/después para ajustar y procesar carpetas enteras. Todo corre en tu computadora (CPU; GPU Intel/NVIDIA opcional vía OpenVINO/Vulkan), sin enviar fotos a ningún servicio.

Local MCP server for AI photo editing and enhancement, plus a before/after web viewer. Runs fully offline.

Qué hace

Mejora y restauración

Edición clásica: auto_enhance, adjust (brillo, contraste, saturación, calidez, gamma, nitidez), denoise, transform (recortar, redimensionar, rotar, convertir), image_info.

Comparar y procesar en lote: compare, compare_gallery, open_viewer, save_preset, list_presets, apply_preset.

Cada herramienta devuelve una vista previa para que el agente vea el resultado. Las fotos originales nunca se modifican: todo lo que se genera va, por defecto, a la subcarpeta mejoradas/ de la carpeta de las fotos (se crea sola). Las herramientas que procesan carpetas y el visor guardan con el mismo nombre que el original; las herramientas de una sola foto agregan un sufijo (DSC_0056_scene_nublado.jpg) para no pisar otras versiones. Todas aceptan otra carpeta o ruta de salida si se indica.

Related MCP server: ImageSorcery MCP

Visor web

• Deslizador antes/después con zoom y paneo.

• Histograma RGB y de luminosidad con recorte de sombras, luces y color medido por canal, y comparación con la original.

• Cada control muestra en su barra: verde sin recorte, amarillo recorte tolerable (manchas chicas y dispersas, como reflejos), rojo recorte visible (zonas continuas, como un cielo quemado) y gris recorte visible causado por otros ajustes. Los umbrales están en clipping.py.

• Recorte y rotación: rectángulo con proporciones fijas (libre, original, 1:1, 4:3, 3:2, 16:9, 4:5, 2:3), enderezado en tiempo real (±45°, sin esquinas vacías) y giros de 90°. Si el recorte deja la foto chica, al guardar se reescala hasta cerca del tamaño original: ×2-×3 con Lanczos de alta calidad (comparado contra detalle real, es más fiel que la IA a ese factor) y ×4 con IA (realesr-general-x4v3). El recorte es de cada foto: no se copia en presets ni en lotes, y los lotes conservan el recorte que ya tenía cada foto.

• Panel en dos pestañas: Automática / IA (botón Analizar y mejorar con IA, que diagnostica la foto —escena, exposición, recortes, ruido, color— y busca los parámetros óptimos con el mismo procedimiento determinista que auto_tune, mostrando un informe; perfil de escena e intensidad) y Manual (brillo, contraste, saturación, calidez, gamma, nitidez; copiar/pegar y ajustes guardados). Los dos modos se combinan. La mejora automática clásica (auto_enhance) queda solo como herramienta MCP: el perfil hace lo mismo con mejores métodos y sumarlas recortaba luces, sombras y color.

• Perfiles de escena (automático o manual) con intensidad regulable.

• Controles en vivo: mejora automática, brillo, contraste, saturación, calidez, gamma, nitidez.

• Ajustes guardados con nombre y aplicación en lote a las fotos seleccionadas. Si la foto actual se mejoró con el análisis con IA, el lote analiza cada foto seleccionada por separado y guarda su propio óptimo (conservando su recorte), en vez de copiar el de una a las demás.

• Siempre parte del original: los ajustes no se acumulan.

.venv/bin/python server.py viewer ~/Fotos/viaje            # editadas en ~/Fotos/viaje/mejoradas
.venv/bin/python server.py viewer ~/Fotos/viaje ~/otra 8770  # otra carpeta de salida y otro puerto

Abre http://127.0.0.1:8765/. También se puede abrir desde el agente con la herramienta open_viewer (en ese caso vive mientras viva el servidor MCP).

En Windows: .venv\Scripts\python.exe server.py viewer C:\Fotos\viaje.

Para que siga corriendo aunque cierres la terminal o el agente (hasta reiniciar la PC), en Linux:

systemd-run --user --unit=visor-fotos "$PWD/.venv/bin/python" "$PWD/server.py" viewer ~/Fotos/viaje
systemctl --user stop visor-fotos   # para apagarlo

En Windows, sin ventana de consola: Start-Process .venv\Scripts\pythonw.exe -ArgumentList 'server.py','viewer','C:\Fotos\viaje'.

Instalación

Funciona en Linux, Windows y macOS (x86_64). Cada cambio se prueba automáticamente en Linux y Windows con GitHub Actions, instalando desde una carpeta con tildes y eñes en el nombre. Memoria: 8 GB de RAM como mínimo. Un perfil de escena sobre una foto de 24 MP usa ~4 GB, por eso el procesamiento en lote con perfil de escena trabaja de a una foto (sin perfil, de a tres).

Linux / macOS

git clone https://github.com/mzwenger/photo-enhance-mcp
cd photo-enhance-mcp
./setup.sh

Windows (PowerShell)

git clone https://github.com/mzwenger/photo-enhance-mcp
cd photo-enhance-mcp
powershell -ExecutionPolicy Bypass -File setup.ps1

El instalador (install.py) instala uv si falta, crea un entorno Python 3.12 (no hace falta tener Python instalado), instala PyTorch para CPU y descarga los modelos (~2 GB) en models/ y bin/, incluido Real-ESRGAN para tu sistema. Algunos modelos (CLIP, métricas de pyiqa, el codificador de texto de InstructIR) se descargan solos la primera vez que se usan.

El reescalado de fotos con IA (realesr-general-x4v3) corre en CPU. Real-ESRGAN x4plus, que se usa solo para ilustraciones, usa la GPU por Vulkan; si no hay Vulkan, cae a un reescalado clásico y lo avisa.

Conectarlo a Claude Code

Linux / macOS:

claude mcp add --scope user photo-enhance -- "$PWD/.venv/bin/python" "$PWD/server.py"

Windows:

claude mcp add --scope user photo-enhance -- "$PWD\.venv\Scripts\python.exe" "$PWD\server.py"

O agregá a ~/.claude.json (en Windows, %USERPROFILE%\.claude.json, con rutas como C:\\Users\\vos\\photo-enhance-mcp\\.venv\\Scripts\\python.exe):

{
  "mcpServers": {
    "photo-enhance": {
      "type": "stdio",
      "command": "/ruta/a/photo-enhance-mcp/.venv/bin/python",
      "args": ["/ruta/a/photo-enhance-mcp/server.py"]
    }
  }
}

Después pedile al agente cosas como "mejorá las fotos de ~/Fotos/viaje con el perfil automático" o "borrá el cartel de esta foto y subile la resolución".

Aceleración por hardware (opcional)

• GPU Intel: sudo apt install intel-opencl-icd libze-intel-gpu1 y OpenVINO la usa sola.

• Para forzar un dispositivo: IMAGE_KIT_DEVICE=CPU|GPU|NPU.

• Memoria del servidor: los modelos quedan cargados para responder rápido y se descargan solos cuando el proceso supera IMAGE_KIT_MAX_RAM_GB (3 por defecto). Con más RAM, subirlo acelera las llamadas seguidas.

Estructura

server.py       servidor MCP, herramientas clásicas y visor web
scenes.py       mejora natural por escena y detección de escena
autotune.py     búsqueda determinista de parámetros óptimos
clipping.py     recorte tolerable vs visible (tamaño de mancha y total por tipo)
ai_enhance.py   3D LUT, InstructIR, DDColor y puntaje de calidad
ai/instructir/  arquitectura de InstructIR (MIT, ver su LICENSE)
install.py      instalación multiplataforma y descarga de modelos
setup.sh        instalador para Linux y macOS (instala uv y ejecuta install.py)
setup.ps1       instalador para Windows
tests/          prueba de humo (MCP y visor), la misma que corre GitHub Actions

Licencias

El código de este repositorio es MIT (ver LICENSE). Los modelos y algunas dependencias tienen licencias propias que se aplican a su uso:

Revisá la licencia de cada proyecto antes de un uso comercial.

Créditos

LaMa · GFPGAN · Real-ESRGAN · rembg · InstructIR · DDColor · Image-Adaptive 3D LUT · IQA-PyTorch · CLIP · OpenCV Zoo · exportes ONNX de FaceFusion y Carve.