Z-Image Studio provides an MCP server that exposes image generation tools, model listing, and generation history over the Model Context Protocol. Once installed, you can run the MCP server to allow local or remote agents to request image generations, query available models, and fetch generation history via the /mcp endpoint. The server supports multiple transport modes (stdio, SSE, and Streamable HTTP) to maximize compatibility and performance, with the recommended approach being Streamable HTTP at /mcp for production use, and SSE at /mcp-sse as a fallback.

Using the MCP features, agents can request image generations with associated parameters, list supported models for the current hardware, and retrieve historical results to track outputs. The CLI and Web UI provided by Z-Image Studio remain available for interactive use, but the MCP server enables integration with automation pipelines and AI agents by exposing a standardized content format across transports.

Prerequisites:

• Python 3.11+ and uv (uvt or uv runner) installed
• Optional GPU drivers supporting CUDA/ROCm/MPS as per your platform

Installation steps:

1. Install uv tool if you don’t have it:
   • pipx install uv
   • or using uv directly if you have it installed via uv tool
2. Install the Z-Image Studio MCP server via uv tool install: uv tool install git+https://github.com/iconben/z-image-studio.git

   or clone locally and install from source, then install the tool

3. Start the MCP server (stdio + SSE + Streamable HTTP):
   • zimg mcp
   • or if you installed as a local repo, run the equivalent entrypoint, e.g. zimg-mcp
4. Verify the server is running by hitting the MCP endpoint:
   • Streamable HTTP: http://localhost:8000/mcp
   • SSE: http://localhost:8000/mcp-sse

Notes:

• The MCP server exposes endpoints for image generation, model listing, and history via a standardized transport protocol.
• If you want to customize behavior (output paths, torch compile, etc.), set environment variables or a config JSON as indicated in the environment variables section of the config.

Tips and common issues:

• Ensure Python 3.11+ is used; Python 3.12+ may require experimental flags for torch.compile.
• If the server cannot detect a suitable GPU, it will fall back to CPU; check your PyTorch installation and device visibility.
• For AMD ROCm setups, verify ROCm drivers are installed and PyTorch is built with ROCm support; environment hints like HSA_OVERRIDE_GFX_VERSION may be needed for some GPUs.
• The MCP transport is designed to be transport-agnostic; prefer Streamable HTTP (/mcp) for best performance, falling back to SSE (/mcp-sse).
• You can control output directories and configuration via ZIMAGE_OUTPUT_DIR and ZIMAGE_CONFIG env vars.