hypersniper05/mcp-image-generator-uncensored

Make your own ``

A self-hosted Model Context Protocol server that makes and edits images and videos on your own computer: images with Qwen-Image-2.1, videos with Kandinsky 6 (optional). Ask for an image or a video in VS Code, Cursor, Claude Code, LM Studio or any other MCP client on your network, and it appears in the chat.

Your GPU, your images. No cloud, no account, no content filter.

• Text to image
• Edit
• Restoration
• Text in images
• Transparent PNG
• Seamless texture
• 360 panorama
• Upscale
• Watermark removal
• SVG
• Video, Animation and GIF (optional video extension)

• Easy to run. Install Docker, then run start.cmd (Windows) or ./start.sh (Linux). Press Enter at each question. The script finds your GPU, picks the model, downloads it and starts the server.
• Low VRAM. It runs on a 4 GB NVIDIA GPU. What does not fit on the GPU stays in RAM. You can also split the model over several GPUs and the CPU. See GPU memory.
• Fast. Turbo makes a 1344x768 photo in 5 s on an RTX 5090 and in 12 s on an RTX 3080 Ti.
• Quality. The Non-Turbo model writes small text well and follows long prompts closely. See Turbo or Non-Turbo.
• Mac. For now, Docker on a Mac uses only the CPU. A native version for the Apple GPU is in development: see Mac.

Gallery

The Non-Turbo model made these images with its default quality settings. Turbo made the restoration example, the love letter, the menu, the newer transparent images and the sources for the SVGs and animations. The video extension made the videos, animations and GIFs. The prompts are in the table below.

Make your own Text to image

Any size or aspect ratio, up to about 4 megapixels (2048x2048). Famous characters too, which many image services refuse.

Make your own Edit

Change, add or remove things, restyle, or combine up to 10 images. Here the lighthouse becomes a snowy winter night.

Make your own Restoration

Old, scratched or faded photos: ask edit_image to restore them, and to add color if you like. The old photo here is made up, damage included.

Make your own Text in images

Text in quotes in the prompt is written as given.

Make your own Transparent PNG

A transparent background straight from the prompt, or remove_background on any image. Hair, petals and soft edges stay clean.

Make your own Seamless texture

Each tile (top) repeats with no seams (bottom, 3x3). Edits of a tile stay seamless, such as height and normal maps.

A stone tile, then a height map and a normal map made from it with an edit, each repeated 2x2.

Make your own 360 panorama

A full 360 view, with a link to the built-in 360 viewer in the result. image turns a photo into a panorama.

Make your own Upscale

2x or 4x, up to 8192 px per side. Left: plain enlargement. Right: the upscaler.

Make your own Watermark removal

Watermarks, logos and overlaid text go; the rest of the image stays as it was.

Make your own SVG

generate_image, then vectorize_image: a real SVG file, as your browser draws it. Logos, icons, lettering and line art stay sharp at any size, and you can edit and recolor them in any vector app.

Each pair is a zoomed detail: the PNG on the left, the SVG on the right.

Make your own Video

5 to 20 seconds with sound, from text or from an image (here the 360 panorama). Click a preview for the full video with sound. Needs the optional video extension.

Make your own Animation

Transparent animations for games, apps and stickers: start from a transparent image and add transparent: true. The result is a WebM with transparency and an animated WebP like these, which play over any background.

Make your own GIF

gif: true on a new video, or video_to_gif on any video. A transparent video gives a transparent GIF.

Prompts and settings

Quick start

New to Docker or MCP? Getting started shows each step of the setup, each choice and what the screens mean.

1. Install Docker (see Requirements) and start it. On Windows, open Docker Desktop and wait until it shows that it is running.

2. Download this project with Git:

   git clone https://github.com/hypersniper05/MCP-Image-Generator-Uncensored.git
   cd MCP-Image-Generator-Uncensored
   

   Without Git: on GitHub click Code > Download ZIP and unzip it (updates then mean downloading it again).

3. Run the start script from that folder:

   • Windows: double-click start.cmd
   • Linux: run ./start.sh
   • Mac: double-click start.command (CPU only for now, see Mac)

4. The first start runs the setup. It asks which GPU (when there are several) and which model to use (see Choosing a model). It sets the GPU memory settings for you. If you are not sure, press Enter to take the recommended choice (Turbo). Choose 1 or 2 for the Non-Turbo model. Getting started explains each choice.

5. Wait. The first start builds the Docker image (10-30 minutes, 16 on a fast PC). Then it downloads 11-16 GB of models into the models folder (Turbo: 13 minutes on a 1 Gbps line). When it is ready, the script prints the address:

   Ready. Add this address to your AI app as an MCP server:
       http://localhost:5005/mcp
   

6. Add that address to your MCP client (see Connect an MCP client).

• Change the model or the GPU: run setup.cmd (Windows) or ./setup.sh (Linux). Your current settings are the defaults, so Enter keeps them.
• Update: run update.cmd or ./update.sh. Your settings and model files are kept.
• Stop: stop.cmd or ./stop.sh. Logs: docker compose logs -f.
• A message you do not understand: see When something goes wrong.
• Web gallery: open http://localhost:5005/ (see The web gallery).
• Model files are saved in the models folder. After you change the model, the old files stay there: delete the ones you no longer use to free disk space.
• Settings: your choices are saved in config.yaml (created from config.example.yaml).
• Updates by hand: git pull, then ./start.sh --build (or start.cmd -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, see every image on the server and delete images from its web page, and so can a web page open in a browser on your network (except deleting: only the server’s own page can do that). 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.

The web gallery

Open http://localhost:5005/ in a browser on your network.

• Every image and video on the server, by folder and day. Search names and prompts, filter by type (generated, edit, transparent, tile, panorama, upscaled, SVG, video, GIF, animation, upload) and sort by date, name or size. Videos play in the viewer.
• Select many images (their check marks, Ctrl+click, Shift+click for a range, Ctrl+A), then download them as a zip or move them to the trash. Undo brings them back, and so does the trash until you empty it or the outputs cleanup removes old files (outputs.keep_days).
• Click an image to see it full size with its prompt and settings, and copy its reference for your AI app.
• Drop images on the page to upload them as inputs for edits.

To stop the page from deleting images, set outputs.allow_delete: false in config.yaml.

Turbo or Non-Turbo

The choice is yours during the setup.

Recommended setup: Turbo Q4_K_M with the Q4_K_M text encoder. The setup recommends it, so Enter picks it. It downloads 11.4 GB. The whole model needs about 14 GB of GPU memory. For the Non-Turbo model, choose 1 or 2 in the setup.

With less GPU memory, the server keeps more weights in RAM. On the same GPU this costs little time from 8 GB, and 4-6 GB takes about 2 times longer. An older GPU or a slow PCIe slot is slower again: see GPU memory.

Turbo, seconds per image:

The 3080 Ti uses the limit that the setup sets: 10 GB. Smaller GPUs: see GPU memory.

Mac: on a MacBook Pro M5 Max, Docker uses only the CPU, and Turbo took 148 s at 512x512. The native version for the Apple GPU, in development, took 11 s at 512x512, 48 s at 1024x1024 and 69 s for an edit. See Mac.

First install: about 30 minutes on a fast PC with a 1 Gbps line. The build took 16 minutes (10-30 minutes, depending on the CPU), and the Turbo download (11.4 GB) took 13 minutes. After that, the server is ready about 35 s after a start.

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

The setup sets everything for your GPU. Choose one GPU and the model goes on it. What does not fit stays in RAM: the engine decides this by itself. On a 12 GB GPU, for example, it keeps the text encoder’s weights in RAM.

Docker on a Mac uses only the CPU and RAM, with no GPU: see Mac.

Turbo, seconds per image, with what the setup sets for each GPU size:

All rows come from one RTX 3080 Ti, with the memory limit that the setup sets for each GPU size. They show the cost of less memory, not of a slower GPU. So the 4-8 GB rows are estimates: a real card of that size is slower.

An old PC is much slower. On a real GTX 1650 4 GB, one image took 618 s at 1344x768, 632 s at 1024x1024 and 110 s at 512x512, using 2.2 GB of GPU memory. The GTX 1650 has about 11 times less FP32 compute than an RTX 3080 Ti (3 against 34 TFLOPS) and no tensor cores. That PC also had 16 GB of DDR3 RAM and a hard disk. Docker had 12 GB of that RAM, so the server read the text encoder from the disk for each image.

Split the model over GPUs and the CPU

The model has three parts. Each part can run on a different GPU, or on the CPU. With two or more GPUs, choose Custom load (multi-GPU and CPU) in the setup (see Custom load). With one GPU, set the parts in config.yaml (see Choosing GPUs).

• In Custom load, the setup recommends the text encoder in RAM on a GPU with 12-19 GB. Its weights (5.0 GB, or 8.7 GB with the Q8_0 file) then stay out of GPU memory (on a 12 GB GPU, the engine also does this by itself). On a GPU with 8-11 GB this was slower (19.4 s against 11.8 s at 1344x768), so the setup does not recommend it there.
• The image decoder on the CPU makes each image much slower. Use it only when no GPU has room.

Choosing a model

The setup asks which model to use (the first start runs it). Run setup.cmd or ./setup.sh at any time to change it.

• Time, GPU memory and RAM: one 1024x1024 image on an RTX 3080 Ti 12 GB, with the 10 GB limit that the setup sets for it. What does not fit in GPU memory stays in RAM.
• GPU: Turbo runs on a GPU with 4 GB or more. For Non-Turbo, use a GPU with 12 GB or more: it makes 40 steps per image, so it gets slow when its weights stay in RAM.
• Memory for Docker: 16 GB for Turbo and Standard, 20 GB for Best quality. The setup checks this.
• Mac: on an M5 Max with the native version in development, one 1024x1024 image took 48 s with Turbo and 7-7.6 minutes with Non-Turbo. See Mac.
• Download: each one includes 2.2 GB of files that every choice needs (the text encoder’s vision file, the image decoder, background removal, watermark removal, upscaler).

Turbo is the official Qwen-Image-2.1-Turbo: it is much faster, but weaker at small text and at following long prompts. Non-Turbo is Qwen-Image-2.1 in a GGUF build by abenzerps, chosen because it keeps its quality well at 4-bit.

Same prompt and seed with each combination (click to see full size). The Non-Turbo model with the Q8_0 text encoder gave the best quality. On a 12 GB card, the larger Turbo files (Q5_K_M, Q6_K) were slower than Q4_K_M because they do not fit as well.

To pick another combination, set model.variant, model.quant and model.text_encoder_quant in config.yaml. config.example.yaml lists the sizes. Then run the start script again and let it restart the server.

Connect an MCP client

The endpoint is http://: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" } } }

Claude Code: run this once in a terminal:

claude mcp add --transport http imagegen 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).

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://: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, and vectorize_image a link to the SVG file.

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”.

Video extension

An optional extension makes 5 to 20 second videos with sound from a text description or from an image, and transparent animations for games and UIs, and GIFs. It uses Kandinsky 6 Lite in a 4-bit version, runs in its own container in extensions/kandinsky6/, and its tools appear on the same MCP address as the image tools. The setup asks whether to install it. To uninstall it, run the setup again and answer no.

Kandinsky 6 Lite is a small model (3 billion parameters). It does best with calm motion that needs no physics: idle loops, steam, flames, blinking, small gestures and slow camera moves. Fast action and things that collide or interact often go wrong.

In the works: an extension for MiniMax-H3, a large video model (33 billion parameters) that handles fast action and complex motion, for GPUs with more memory.

See Kandinsky 6 video for the samples, the options, how to prompt, the token limits, and the speed and memory on different GPUs.

Configuration

All settings are in config.yaml (created from the commented config.example.yaml). After a change, run the start script again and let it restart the server. 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. The setup can do this for you: choose Custom load (multi-GPU and CPU) (see Getting started). By hand, in config.yaml:

gpu:
  diffusion: [0]     # the image model: runs every step, use the fastest GPU
  text_encoder: 1    # reads the prompt once per request
  vae: 0             # the image decoder: 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: run the setup again and choose Turbo, use a smaller size, or move a part of the model to another GPU (see Split the model over GPUs and the CPU).
• 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 or the Q8_0 text encoder 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.
• Images fail with “lost the connection to the inference engine”: the engine stopped, usually because it ran out of memory. Give Docker more memory (see the Windows item above) or choose a smaller model.
• The server shows an error: read docker compose logs --tail 100, fix the cause, and run the start script again. Getting started lists the messages of the scripts and what to do.

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.

Contribute

• Bug reports and ideas: open an issue.
• Pull requests are welcome. Run the tests first: see Development.

Origins & License

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. The video extension uses parts with their own limits: the audio decoder allows non-commercial use only, and the video VAE’s license does not cover the EU, the UK or South Korea. Read them before you install the extension there or use its videos commercially. Only remove watermarks from images you have the rights to edit. The :gpu Docker image is based on NVIDIA’s CUDA image (license).

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