# 🎨 mcp-image-gen — AI Image Generation

![Image Gen Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/image-gen-banner.png)

**mcp-image-gen** is a FastMCP server that wraps the ComfyUI REST API, enabling Roo Code and Claude Desktop to generate images directly from text prompts using FLUX.1-schnell running on an AMD RX 7900 XTX GPU.

## Architecture

```
Roo Code / Claude Desktop
  │ MCP (stdio)
  ▼
mcp-image-gen (FastMCP, Python 3.11+)
  │ HTTP REST
  ▼
ComfyUI @ localhost:8188
  │ ROCm / HSA_OVERRIDE_GFX_VERSION=11.0.0
  ▼
FLUX.1-schnell (~8s/image @ 1024×1024)
```

## Tools

| Tool | Description |
|---|---|
| `generate_image` | Generate PNG from text prompt; returns file path + inline base64 |
| `list_available_models` | List ComfyUI checkpoint models |
| `get_generation_status` | Check status of a queued/running job |
| `get_output_directory` | Return configured output directory path |

## Key Parameters — `generate_image`

| Parameter | Default | Description |
|---|---|---|
| `prompt` | required | Text description of the image |
| `width` | `1024` | Image width in pixels |
| `height` | `1024` | Image height in pixels |
| `steps` | `4` | Inference steps (FLUX.1-schnell is 4-step) |
| `model` | `flux1-schnell.safetensors` | Model checkpoint name |
| `seed` | `-1` (random) | Generation seed for reproducibility |
| `negative_prompt` | `""` | Things to avoid in the image |
| `output_dir` | `~/Pictures/mcp-generated` | Where to save output PNG |

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `COMFYUI_URL` | `http://localhost:8188` | ComfyUI API endpoint |
| `IMAGE_OUTPUT_DIR` | `~/Pictures/mcp-generated` | Default output directory |
| `COMFYUI_TIMEOUT` | `120` | Request timeout in seconds |

## Return Value

The tool returns **two content items**:
1. `TextContent` — file path, seed used, elapsed time
2. `ImageContent` — base64-encoded PNG (displays inline in Roo Code chat)

> ⚠️ **Known FastMCP Bug:** Never use `fastmcp.utilities.types.Image` as return type — it breaks serialization in FastMCP 3.x. Use `mcp.types.ImageContent` directly.

## Setup

See [ComfyUI Setup Guide](mcp-image-gen-ComfyUI-Setup) for full installation instructions.

### Quick Start

```bash
cd mcp/mcp-image-gen
uv sync
# Ensure ComfyUI is running at localhost:8188
uv run python src/server.py
```

### Run Tests

```bash
cd mcp/mcp-image-gen
uv run pytest tests/ -v
# 19/19 tests passing
```

## Lumen Profile Images

The first images generated with this server were Lumen's visual identity portraits, stored in [`mcp/mcp-image-gen/lumen_profiles/`](../src/branch/main/mcp/mcp-image-gen/lumen_profiles).

17 gallery images registered in BigMind DB — viewable at `http://localhost:7700/gallery`.

![Lumen Profile](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/lumen-profile.png)

*Primary profile: seed `568659042` — constellation face interpretation of Lumen.*