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.

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