Content
# Local ImageGen MCP Server
A Python-based general-purpose image generation MCP server, providing:
- Text-to-image generation
- Image editing based on reference images
- Automatic GPU selection based on available VRAM
- Automatic decision to enable CPU offload based on VRAM availability
- Conversion of user requests to English prompts before inference
Default model reference: `examples/inference.py`, using `black-forest-labs/FLUX.2-klein-9b-kv`.
## Requirements
- Anaconda `base` environment
- Python 3.11+
- Available CUDA GPU
This repository directly reuses the `base` environment without creating an additional virtual environment.
## Installation
First, activate the `base` environment:
```bash
conda activate base
```
Then, install as an editable package in the repository root directory:
```bash
python -m pip install -e .
```
## Building
```bash
conda activate base
python -m build
```
## Starting the Server
```bash
conda activate base
python -m local_imagegen_mcp
```
The server uses `stdio` transport, suitable for direct use with Codex or other MCP clients.
## MCP Tools
- `generate_image`: Generate an image based on a text request
- `edit_image`: Edit an image based on an input image
Both tools return:
- A text summary containing the final English prompt, output path, seed, and device information
- An image result
## Runtime Behavior
The model is lazily loaded only upon receiving the first image generation request. Before each request:
1. Check the available VRAM on each GPU
2. Select the GPU with the most available VRAM
3. Decide whether to use the GPU directly or enable offload based on a threshold
4. Convert the user's request into an English prompt more suitable for the image model
## Environment Variables
Runtime behavior can be adjusted through environment variables:
- `LOCAL_IMAGEGEN_MODEL`: Model name, default `black-forest-labs/FLUX.2-klein-9b-kv`
- `LOCAL_IMAGEGEN_OUTPUT_DIR`: Output directory, default `<repo>/outputs`
- `LOCAL_IMAGEGEN_OFFLOAD_THRESHOLD_GB`: Enable `enable_model_cpu_offload` when the selected GPU's available VRAM falls below this value, default `20`
- `LOCAL_IMAGEGEN_SEQUENTIAL_OFFLOAD_THRESHOLD_GB`: Enable `enable_sequential_cpu_offload` when the selected GPU's available VRAM falls below this value, default `12`
- `LOCAL_IMAGEGEN_FORCE_DEVICE`: Optional, force usage of `cuda:0`, `cuda:1`, or `cpu`
- `LOCAL_IMAGEGEN_FORCE_OFFLOAD`: Optional, force enabling offload, supporting `model` or `sequential`
## Configuring Codex MCP
Can be added using the CLI or by editing `~/.codex/config.toml` or the project-specific `.codex/config.toml`.
### Method 1: CLI
```bash
codex mcp add local_imagegen \
--cwd /absolute/path/to/LocalImageGen \
--env LOCAL_IMAGEGEN_MODEL=black-forest-labs/FLUX.2-klein-9b-kv \
--env LOCAL_IMAGEGEN_OUTPUT_DIR=/absolute/path/to/LocalImageGen/outputs \
--env LOCAL_IMAGEGEN_OFFLOAD_THRESHOLD_GB=20 \
--env LOCAL_IMAGEGEN_SEQUENTIAL_OFFLOAD_THRESHOLD_GB=12 \
-- conda run --no-capture-output -n base python -m local_imagegen_mcp
```
### Method 2: `config.toml`
```toml
[mcp_servers.local_imagegen]
command = "conda"
args = ["run", "--no-capture-output", "-n", "base", "python", "-m", "local_imagegen_mcp"]
cwd = "/absolute/path/to/LocalImageGen"
startup_timeout_sec = 120
tool_timeout_sec = 1800
[mcp_servers.local_imagegen.env]
LOCAL_IMAGEGEN_MODEL = "black-forest-labs/FLUX.2-klein-9b-kv"
LOCAL_IMAGEGEN_OUTPUT_DIR = "/absolute/path/to/LocalImageGen/outputs"
LOCAL_IMAGEGEN_OFFLOAD_THRESHOLD_GB = "20"
LOCAL_IMAGEGEN_SEQUENTIAL_OFFLOAD_THRESHOLD_GB = "12"
```
After configuration, you can view the server and tools through `/mcp` in the Codex CLI or IDE extension.
## Development Verification
After installation, local verification can be performed:
```bash
conda activate base
python -m unittest discover -s tests
python tests/verify_mcp_discovery.py
python -m build
```
## Notes
- Initial model loading may be slow and may trigger model download
- Chinese requests can be directly passed in, and the server will convert them into English-style image prompts for inference
- Image outputs are saved as PNG by default
