Skip to main content
Glama
Sign In
zimage-mcp

zimage-mcp

by sjemmeh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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: image-studio-mcp

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

Available Tools

3 tools
generate_imageA

Generate web-dev image(s) with Z-Image Turbo and save to output_path.

size: one of square|landscape|portrait|hero|wide|og|mobile, or pass width+height for exact pixels (image is generated at the nearest valid size then resized/cropped). n: 1-4 variants (paths get _1,_2,... ); seeds are base_seed, base_seed+1, ... Returns {images, seed, gen_size, output_size, seconds}.

Inputs: prompt (required), output_path (required), n, seed, +5 more.

healthA

Quick ComfyUI pre-flight: version, GPU, free VRAM.

Inputs: no named parameters.

list_presetsA

Return available size presets as name -> 'WxH'.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a distinct purpose: generate_image for creation, health for system status, list_presets for configuration. No overlap or ambiguity.

    Naming Consistency4/5

    Most tools follow verb_noun pattern (generate_image, list_presets), but 'health' is a noun alone. Minor deviation but still clear and readable.

    Tool Count5/5

    Three tools is well-scoped for an image generation server: core generation, health check, and preset listing. No unnecessary bloat.

    Completeness5/5

    The tool set covers the essential workflow: generate images, check system readiness, and retrieve presets. No obvious missing functionality for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers