MCP Image Generator (Uncensored)

A self-hosted Model Context Protocol server that creates and edits images with the uncensored Qwen-Image-2.1 model on your own computer. It runs in Docker, on an NVIDIA GPU or on the CPU, and any MCP client on your network can use it over Streamable HTTP.

The default model is an uncensored build of Qwen-Image-2.1 with no built-in content filter. To use the standard model instead, set model.variant: base in config.yaml.

• Text to image in any size or aspect ratio, up to about 4 megapixels (2048x2048)

• Image editing: change, add or remove things, restyle, or combine up to 10 images

• Transparent backgrounds (RGBA PNG) and background removal

• Seamless tileable textures, including height and normal maps that stay seamless

• 360 panoramas with a built-in 360 viewer

• Upscaling 2x or 4x, and watermark removal

• Models download automatically on the first start

Examples

All images below were made by this server with the default quality settings. The prompts are listed under the gallery.

360 panorama, opened in the built-in 360 viewer from the link in the result

Seamless textures

Each texture below is one tile (top). Repeated 3x3 (bottom), it shows no seams.

Texture maps: a stone tile, then a height map and a normal map made from it with an edit. Each is shown repeated 2x2: they all stay seamless.

Upscaling 4x. Left: plain enlargement. Right: the upscaler.

Characters and brands shown belong to their owners.

Related MCP server: image-forge-mcp

Requirements

GPU setup

• Windows: install Docker Desktop with the WSL 2 backend and a current NVIDIA driver.

• Linux: install the NVIDIA driver and the NVIDIA Container Toolkit.

Check that Docker can see your GPU:

docker run --rm --gpus all nvidia/cuda:12.8.2-base-ubuntu24.04 nvidia-smi

GPU memory

Every feature, including 2048x2048 images, edits with 10 input images, 2880x1440 panoramas and upscaling to 8192 px, works on a single 12 GB card:

Settings for a 12 GB card, in config.yaml:

gpu:
  max_vram_gb: {0: 10}
  offload: {text_encoder: cpu}
generation:
  prefix_cache_type: q8_0

Quick start

git clone https://github.com/hypersniper05/MCP-Image-Generator-Uncensored.git
cd MCP-Image-Generator-Uncensored
./start.sh            # Linux / macOS

.\start.cmd           # Windows (or double-click start.cmd)

The first start builds the Docker image (10-30 minutes) and downloads about 12 GB of models. When it is ready, the script prints the address:

Ready. MCP endpoint (Streamable HTTP, no auth):
    http://localhost:5005/mcp

• Stop: ./stop.sh or stop.cmd. Logs: docker compose logs -f.

• Web page: open http://localhost:5005/ to see the status, upload images and browse recent results.

• Settings: the first start creates config.yaml from config.example.yaml. To run on the CPU, set device: cpu in config.yaml and run the start script again.

• Updates: after pulling new code, run ./start.sh --build (or start.cmd -Build) to rebuild the image.

cp config.example.yaml config.yaml
cp .env.example .env                  # for CPU mode, set COMPOSE_PROFILES=cpu in .env
docker compose up -d --build

Security note. The server is open by design, so it is easy to connect to: it has no login, it listens on all network interfaces, and it accepts requests from any web page. Anyone who can reach port 5005 can make images and see every image on the server, and so can a web page open in a browser on your network. Run it on your own computer or a network you trust, use a VPN such as Tailscale for remote access, and never forward the port to the internet.

Connect an MCP client

The endpoint is http://<host>:5005/mcp (Streamable HTTP).

MCP Inspector (quick test in a browser): run npx @modelcontextprotocol/inspector, choose Streamable HTTP, enter http://localhost:5005/mcp and click Connect.

VS Code (.vscode/mcp.json):

{ "servers": { "imagegen": { "type": "http", "url": "http://localhost:5005/mcp" } } }

Cursor (~/.cursor/mcp.json) and most other clients:

{ "mcpServers": { "imagegen": { "url": "http://localhost:5005/mcp" } } }

Clients that only support stdio can connect through mcp-remote:

{ "mcpServers": { "imagegen": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:5005/mcp", "--allow-http"] } } }

Large images take minutes. If an image is not ready within 25 seconds, the tool returns a job_id and the client gets the image with get_job, so clients with short time limits still work. To wait longer per call, add ?max_wait=N to the endpoint URL (in seconds, at most 280; keep it under your client's tool time limit).

For the llama.cpp web UI (llama-server started with --ui-mcp-proxy), add the server in the web UI's MCP settings, or for every browser through the file passed with --ui-config-file:

{
  "mcpServers": "[{\"id\": \"imagegen\", \"name\": \"Image Gen\", \"url\": \"http://127.0.0.1:5005/mcp\", \"enabled\": true, \"useProxy\": true, \"headers\": \"{\\\"X-Imagegen-Max-Wait\\\": \\\"20\\\", \\\"X-Inline-Max-Bytes\\\": \\\"16000000\\\"}\"}]"
}

Optional headers a client can send:

Tools

Input images can be a data URL or base64, an http(s) URL, a file name or link of an image this server made, or an image uploaded on the server's web page (http://<host>:5005/upload).

Results include the image (or a preview of a large one) and a link to the full file, which is saved in ./outputs. Panoramas also get a link to the 360 viewer.

Tips

• For the best quality use size: "xl". Leave steps and cfg_scale unset.

• Write full sentences: subject, setting, lighting, style. Put text that should appear in quotes: a neon sign that says "OPEN 24/7".

• For edits, say what to change and add "keep everything else unchanged".

• For tiles, describe a surface or pattern that fills the whole picture, e.g. "moss-covered cobblestones, top-down".

Configuration

All settings are in config.yaml (created from the commented config.example.yaml). Restart after a change: docker compose restart. The most useful ones:

.env (created from .env.example) holds Docker settings such as PUBLIC_URL, HF_TOKEN (only needed if Hugging Face rate-limits your downloads) and the build options.

config.yaml and .env are your local files and are not part of the repository.

Choosing GPUs

GPU numbers are the ones nvidia-smi shows. Everything runs on GPU 0 by default. The model has three parts, and each can go on a different GPU:

gpu:
  diffusion: [0]     # the main model, runs every step: use the fastest GPU
  text_encoder: 1    # reads the prompt once per request
  vae: 0             # turns the result into pixels

On a shared computer, only the GPUs you list are used. For cards with less memory, see GPU memory.

Troubleshooting

• No GPU found: run the nvidia-smi check from Requirements. On Linux, install the NVIDIA Container Toolkit. Or use device: cpu.

• Out of GPU memory: use the 12 GB settings, a smaller size, or move the text encoder to another GPU.

• The client times out: add ?max_wait=N to the endpoint URL (or lower generation.wait_seconds) with N below the client's tool time limit.

• Other computers cannot connect: use this computer's IP address instead of localhost, allow port 5005 in the firewall, and set server.public_url so image links work.

• CPU mode is very slow or crashes on Windows: Docker Desktop gives WSL only half your RAM. Raise it in %UserProfile%\.wslconfig ([wsl2] then memory=24GB), run wsl --shutdown and restart Docker Desktop.

• The server shows an error: read docker compose logs --tail 100, fix the cause, and run the start script again.

Development

python -m venv .venv && . .venv/bin/activate
pip install -e ".[test]"
pytest

python -m imagegen_mcp --config config.yaml --check validates a config file without starting anything. python scripts/smoke_test.py http://localhost:5005/mcp tests a running server.

Images are made by stable-diffusion.cpp, built inside the Docker image from a pinned release with one small patch (docker/patches/sdcpp-circular-json.patch) that turns on its wrap-around mode per request for tileable images.

Credits and licenses

The code in this repository is MIT licensed (see LICENSE). It builds on the work of others; the model files are downloaded from their original sources and keep their own licenses:

The Qwen-Image-2.1 files allow non-commercial use only: read their license before using images commercially. Only remove watermarks from images you have the rights to edit. The :gpu Docker image is based on NVIDIA's CUDA image (license).

The uncensored model has no built-in content filter. You are responsible for how you use it and what you make with it.