# MCP Relight & Harmonize [Health: Active]

**Category:** 🎥 Multimedia Process  
**Repository:** https://github.com/MarwanDevSpace/mcp-relight-harmonize  
**GitHub Stars:** 2  
**npm Downloads (last month):** 120  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-relight-harmonize

## Description
Image relighting and composite harmonization tools that produce structured prompts for image generation models. Local stdio server.

## Tools
Capabilities this server exposes over MCP:

- **analyze_optical_profile** — Mathematical optical metrics, 6 visual layers in `Layers/`, and dynamic `Layer.md`.
- **synthesize_diffusion_prompt** — "nano_banana"
- **generate_relight_variations** — Physical relit images saved into `Layers/` (Ambient, Dramatic, Rim, Mood).
- **harmonize_composite** — Composited image with harmonized CCT, Reinhard color transfer, and contact shadow.
- **list_cached_variations** — Inventory of generated layers and artifacts in the `Layers/` directory.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-relight-harmonize": {
    "command": "npx",
    "args": ["-y","mcp-relight-harmonize"],
    "env": {
      "OUTPUT_CACHE_DIR": ""
    }
  }
}
```

**Requires environment variables:** `OUTPUT_CACHE_DIR` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/mcp-relight-harmonize/readme_