zimage-mcp

A local MCP 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.

Related MCP server: Flux Schnell Server

Size presets

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)

Run / register

Requires uv. Add to ~/.claude.json under mcpServers:

"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

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