MCP Relight & Harmonize

What MCP Relight & Harmonize does

MCP Relight & Harmonize MCP server provides local image-processing tools for optical analysis, relighting, composite harmonization, and image-generation prompt synthesis. It belongs to the 🎥 Multimedia Process category and is intended for workflows where an AI assistant needs to inspect lighting structure before proposing or applying visual changes.

The analysis workflow extracts six images into Layers/: highlights, shadows, ambient occlusion, edges, depth normals, and chroma saturation. The server also produces mathematical optical metrics and a dynamic Layer.md file. These artifacts describe brightness, shadow anchoring, surface detail, depth-related information, and color distribution using the source image.

How it works

The server runs as a local stdio process. Image paths are supplied to the MCP tools, and generated layers or artifacts are written to the configured cache directory, normally Layers/. The documented workflow separates deterministic optical extraction from final image generation: Python performs analysis and decomposition, while an image-generation model uses the resulting observations and prompts for rendering.

synthesize_diffusion_prompt returns two prompt formats: a structured JSON specification containing lighting and optical directives, and a descriptive master prompt. It can target a universal image generator or nano_banana. The documented process requires inspecting the six generated layer images individually before image generation is triggered.

Setup and configuration

Build the project from source with npm install, then compile it with npm run build. The repository also documents npm test for the quality suite and npm run verify for a health check.

Configure the server in an MCP client using a mcp_config.json entry. The local build uses the compiled dist/index.js file and can set OUTPUT_CACHE_DIR to ./Layers. The repository also shows an npx configuration using mcp-relight-harmonize@latest.

Docker deployment is supported over stdio. Build the image with the repository Dockerfile and pass OUTPUT_CACHE_DIR=/app/Layers when running the container.

Tools and capabilities

MCP Relight & Harmonize MCP server exposes these tools:

• analyze_optical_profile calculates optical metrics, extracts the six visual layers, and creates Layer.md.
• synthesize_diffusion_prompt creates detailed JSON and master descriptive prompts from an image and optional intent.
• generate_relight_variations creates Ambient, Dramatic, Rim, and Mood relighting images in Layers/.
• harmonize_composite combines foreground and background images with harmonized color temperature, Reinhard color transfer, and contact shadow.
• list_cached_variations inventories generated layers and artifacts in the cache directory.

The tools accept image paths and optional settings such as user intent, target lighting, output directory, blend mode, target model, and cache directory, depending on the operation.

Limitations and notes

The server does not create the final modified image as part of its Python optical-analysis role. Instead, it produces layers, relighting references, composite output, and prompts for use in the wider image-generation workflow. The repository identifies Google Antigravity as its preferred environment because it can provide native image generation, but the MCP process itself is configured as a local stdio server.

The server is documented to use Layers/ exclusively for its generated layer and artifact files; it does not create Variations/ or generated_variations/ directories. The output location can be changed through the cache or output-directory settings exposed in the configuration and tools. The project is licensed under MIT.