# zimage-mcp

A local [MCP](https://modelcontextprotocol.io) server for generating **web-dev images** with the
**Z-Image Turbo** model running on the ComfyUI box. It hard-codes the verified Z-Image graph
(UNETLoader + CLIPLoader `lumina2` + ModelSamplingAuraFlow shift 3 + KSampler 8/cfg1/res_multistep/simple),
downloads the result, and saves it to a local path **at exact pixel dimensions**.

It runs alongside the existing `@peleke.s/comfyui-mcp` (which stays for SDXL/FLUX); tools are
namespaced `mcp__zimage__*`.

## Tools

### `generate_image(prompt, output_path, size="square", width?, height?, seed?, steps?=8, negative?="", n?=1)`
Generates and saves image(s).
- `output_path` — local path, e.g. `./public/img/hero.png`. Parent dirs are created. Format follows the
  extension (`.png` / `.jpg` / `.jpeg` / `.webp`).
- `size` — a preset (below), **or** pass exact `width` + `height`. Because Z-Image needs dimensions that
  are multiples of 16, any exact size is generated at the nearest valid size (≥ requested, matching aspect)
  then **resize-cover + center-crop** to your exact pixels.
- `seed` — omitted = random; echoed back in the result for reproducibility.
- `n` — 1–4 variants. Files get `_1`, `_2`, … suffixes; seeds are `base, base+1, …`.
- Returns `{ images, seed, gen_size, output_size, seconds }`.

### `list_presets()`
Returns the preset table (name → `WxH`).

### `health()`
ComfyUI pre-flight: `reachable`, `comfyui_version`, `gpu`, `vram_free_mb`.

## Size presets

| preset | output | use |
|---|---|---|
| `square` | 1024×1024 | cards, avatars, icons |
| `landscape` | 1216×832 | general content images |
| `portrait` | 832×1216 | tall cards |
| `hero` | 1280×720 | 16:9 hero/banner |
| `wide` | 1536×640 | wide banner (12:5) |
| `og` | 1200×630 | OpenGraph/social share |
| `mobile` | 768×1344 | mobile-first portrait |

> Z-Image is tuned around ~1 MP. Very large custom dimensions (>~1.3 MP) may reduce quality or slow down;
> for big hero art, generate at a preset and upscale separately (a 2K upscaler template exists on the box).
> Note: text-in-image is weak — use FLUX/Qwen for legible baked-in text.

## Configuration (env vars)

| var | default |
|---|---|
| `COMFYUI_URL` | `http://10.0.0.109:8188` |
| `ZIMAGE_UNET` | `z_image_turbo_bf16.safetensors` |
| `ZIMAGE_CLIP` | `qwen_3_4b.safetensors` |
| `ZIMAGE_VAE` | `ae.safetensors` |
| `ZIMAGE_DEFAULT_STEPS` | `8` |
| `ZIMAGE_TIMEOUT_S` | `180` |

## Run / register

Requires [`uv`](https://docs.astral.sh/uv/). Add to `~/.claude.json` under `mcpServers`:

```json
"zimage": {
  "type": "stdio",
  "command": "uv",
  "args": ["run", "--directory", "/Users/jaimie/projects/zimage-mcp", "server.py"],
  "env": { "COMFYUI_URL": "http://10.0.0.109:8188" }
}
```

Restart Claude Code; the tools appear as `mcp__zimage__generate_image`, etc.

## Develop / test

```bash
uv sync
uv run pytest -q                       # unit tests (no network)
ZIMAGE_TEST_LIVE=1 uv run pytest -q    # + live tests against the box
```