Z-Image Studio MCP
Local image generation with the Z-Image-Turbo model: a CLI, a web UI and an MCP server with a generate tool.
- 128 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- The server runs a heavy model on your computer and writes images and a LoRA database to user folders.
- The HTTP server listens on a port, so keep it off the external network when it is not needed.
Install
- Works in
Manual install
uv tool install git+https://github.com/iconben/z-image-studio.gitFirst option from the Global installation section: the `zimg` command becomes available from any folder. Update with `uv tool upgrade z-image-studio`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The server runs a heavy model on your computer and writes images and a LoRA database to user folders.
- The HTTP server listens on a port, so keep it off the external network when it is not needed.
This is third-party code. Review the repository files before installing.
What it does
Z-Image Studio runs the Z-Image-Turbo model on your computer and exposes it to agents through MCP. The server provides three tools: `generate` creates an image from a prompt, `list_models` shows available models and `list_history` lists past generations. There are three ways to connect. Local agents use the stdio command `zimg-mcp`, and after `zimg serve` Streamable HTTP at `/mcp` and SSE at `/mcp-sse` are available. The same features exist in the `zimg` command line and in a web UI with LoRA support, applying up to four adapters at once.
Who it is for. Designers and developers who want agent-made images without a cloud API and a fee per frame.
Good fit when
- An agent makes site illustrations and requests to someone else's cloud are unwelcome.
- A style is set through LoRA and up to four adapters with different strengths must be mixed.
- A series of images has to be reproducible by the seed.
- Gemini CLI or Cline are already set up and a local image generator has to be attached to them.
Not a fit when
- The machine has no discrete GPU and little memory: generation on a CPU is slow.
- A model outside the Z-Image family is needed: the tool is built around Z-Image-Turbo and its variants.
- A result is needed within seconds on any laptop: speed depends on the GPU.
Example request
Generate a 1280 by 720 banner: sunset over a mountain lake, photorealistic, and show the history of recent runs.MCP
- Transport
- stdio, http, sse
- Authentication
- not required
Environment variables
ZIMAGE_DISABLE_MCP- A value of 1 disables the MCP endpoints of the web server.
ZIMAGE_BASE_URL- Base URL for links to generated files.
Limitations
Python 3.11 or newer and `uv` are required. Acceleration exists for NVIDIA CUDA, AMD ROCm on Linux, Intel XPU and Apple Silicon; without a compatible GPU generation falls back to the CPU. On Windows AMD cards still run on the CPU because ROCm exists only for Linux. On Python 3.12 and newer `torch.compile` is off by default because of incompatibility with the model architecture. The Windows installer asks for 8 GB of RAM or more, and 16 GB is better for full precision.
How to disable. Remove the z-image-studio entry from the MCP client configuration. On the server side switch the endpoints off with the `--disable-mcp` flag or the `ZIMAGE_DISABLE_MCP=1` variable.
FAQ
How do I connect the stdio server?
Add a `z-image-studio` server with the `zimg-mcp` command and empty arguments to the client configuration. If the client cannot find the command, give the full path.
Which transports exist besides stdio?
After `zimg serve`, Streamable HTTP runs at `/mcp` and SSE at `/mcp-sse/sse`. Clients are advised to try HTTP first and keep SSE as a fallback.
What does generate return?
Three items: text metadata (size, duration, model), an image preview and a link to the result file.
Why does Cline cut generation off?
Cline aborts long calls quickly, so set the `timeout` parameter in its server settings, for example 300 seconds.
Is there a ready installer?
A Windows 10 and 11 installer is on the releases page. Other systems can use `uv tool install`, `pip install z-image-studio` and a Docker image.
Discussion
No questions or reviews yet.
Related
MCP serversMCP server for image generation and editing: Gemini, OpenAI and Seedream with automatic prompt enhancement
RunAPI MCP server: a catalog of 160 models for images, video, music and speech, pricing, task runs and balance
Skill, MCP server and CLI that let any agent call Codex image generation, after picking a style from several directions
A local MCP server for editing and analyzing images: the agent crops frames, finds objects and reads text from photos
A remote MCP server with 40 tools: a 3D model from text or a photo, rigging, animation, retexturing and GLB checks
An MCP server for generating images and video from the agent: several models, a large prompt library and parallel tasks
README in short
The project builds three interfaces around one model: a command line, a web UI and MCP. The image directory and configuration are set through a file and environment variables.