ImageGen MCP server
Commit Nov 14, 2026Enables AI agents to generate and edit images locally on Apple Silicon using the Qwen-Image 2.1 model.
Also known as ph1lb4/imagegen-mac
- Stars
- 13
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is ImageGen MCP?
ImageGen enables AI agents to generate and edit images locally on Apple Silicon using the Qwen-Image 2.1 model.
Summary generated from the project's README
About ImageGen MCP server
Developers using Claude Code, Cursor, or other MCP clients can generate and edit images locally on Apple Silicon using this server. By running the Qwen-Image 2.1 model directly on your Mac's GPU via Metal, it provides a private way to create visual assets without relying on cloud services or paying per-image fees. The setup requires a Mac with macOS 14 or later and is optimized for machines with 64 GB of unified memory to handle the 33 GB model requirements.
Integration is handled through a native SwiftUI application that manages the Python engine and model downloads from Hugging Face. Once the app is running, you can connect your AI agent using a simple command to point to the local HTTP transport. The server provides specific tools like generate_image for text-to-image tasks, edit_image for modifying existing visuals or combining up to 10 reference images, and list_recent_images to track previous results. Because the processing happens entirely on-device, your prompts and generated files never leave your hardware.
What you can do with it
- 1Generate project assetsAsk your coding agent to create a transparent icon for a specific file and save it directly into your project folder.
- 2Create readable typographyUse the model to generate images that include clear, legible text as part of the design.
- 3Iterate with fast draftsRequest low-resolution drafts to quickly test different prompts before committing to a high-quality render.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableph1lb4/imagegen-mac is public and reachablegithub.com/ph1lb4/imagegen-mac ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/ph1lb4/imagegen-mac ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubImage generation used to mean a cloud service, a monthly bill and your prompts on someone else's server. Not anymore. A state-of-the-art image model now fits in about 33 GB of memory. That's a MacBook Pro or Mac Studio with 64 GB of unified memory.
ImageGen is a native macOS app that downloads the model, runs it on your Mac's GPU (Metal) and gives you a clean studio to work in. It also runs an MCP server, so your coding agent can make images while you work.
Features
- Fully on-device. Prompts and images never leave your Mac. Works offline once the model is downloaded.
- Text to image with strong typography. Text inside images actually comes out readable.
- Image editing. Change an image with an instruction, or combine up to 10 reference images.
- Transparent PNGs. Native RGBA output for stickers, icons and assets.
- MCP server for AI agents. Claude Code, Cursor and any MCP client can generate and edit images. Results show up in the app.
- One-click model download from Hugging Face, resumable, right inside the app.
- Memory guards so a big job fails cleanly instead of freezing your Mac.
- Native SwiftUI app with a menu bar icon. The engine keeps serving agents with the window closed.
Gallery
Every image here was generated locally on an M5 Pro MacBook Pro with 64 GB, with a VM and other apps running.
| Text in images. 512 px draft, 20 s | Transparent sticker. 1024 px, 2 min | Low-poly diorama. 1024 px, 2 min |
| Product shot. 2048x1152, 5.5 min | Long exposure. 2048x1152, 5.5 min | Stadium at night. 2048x1152, 6 min |
The app icon was made with ImageGen too.
How fast is it?
Measured on an M5 Pro MacBook Pro with 64 GB unified memory, Qwen-Image 2.1 in bf16:
| Output | Steps | Time |
|---|---|---|
| 512 x 512 (draft) | 20 | ~20 s |
| 1024 x 1024 | 30 to 40 | ~1.5 to 2 min |
| 1728 x 960 | 25 | ~2.5 min |
| 2048 x 1152 | 40 | ~5.5 min |
Loading the model takes about 20 seconds. Draft quality is the fastest way to iterate on a prompt.
Requirements
- Apple Silicon Mac (M1 or newer), macOS 14+
- 64 GB unified memory recommended. The model needs about 33 GB. 48 GB can load it, but only small images will fit
- About 35 GB free disk for the model, plus about 1 GB for the Python environment
- Xcode command line tools and uv to build
Install
git clone https://github.com/ph1lb4/imagegen-mac.git
cd imagegen-mac
./scripts/build-app.sh
open build/ImageGen.app
Copy build/ImageGen.app to /Applications if you like. On first start the app sets up its Python
environment with the bundled uv (a few minutes, about 1 GB). Later starts take seconds.
Then pick Qwen-Image 2.1 or Qwen-Image 2.1 Turbo and hit download. Each is about 33 GB, and the download resumes if it gets interrupted. They are separate downloads; keeping both needs about 66 GB of disk space.
Qwen-Image 2.1 Turbo supports text-to-image, image editing and transparent output with a fixed 8-step sampling schedule. Custom step counts are unavailable for Turbo; quality presets still control resolution. The same memory guards apply. The pinned Diffusers revision includes support for the checkpoint's saved sampling schedule (upstream PR #14950).
Use it from Claude Code (MCP)
With the app running:
claude mcp add --transport http imagegen http://127.0.0.1:7860/mcp --scope user
Now ask Claude Code for an image: "make a transparent app icon of a paper plane and save it to assets/".
The MCP button in the app toolbar has copy-ready snippets for Claude Code and JSON-configured clients
(Cursor, VS Code and others).
| Tool | What it does |
|---|---|
generate_image |
Prompt to image. Aspect ratio, quality (draft/standard/high), transparent, seed, steps, output_path to save into a project |
edit_image |
Edit or combine up to 10 input images with an instruction |
list_models |
Supported models, download and load state |
load_model |
Load an already downloaded model |
get_status |
Engine state and queue |
list_recent_images |
Recent results with prompts and paths |
Results return the PNG path plus a small preview, so the agent can see what it made.
Memory safety
The model needs about 33 GB, and generation needs more on top. If a Mac runs out of memory, macOS swaps until the machine freezes. The engine has three guards against that:
- GPU memory cap. PyTorch may use total memory minus 30% (at least 12 GB stays free), so 48 GB on a
64 GB Mac. A job that needs more fails with an error instead of swapping. Override with
IMAGEGEN_GPU_MEMORY_LIMIT_GB. - Size cap. "High" is 2048 px on Macs with 96 GB+ and 1536 px below that. Larger sizes are rejected before they start. Large images are decoded in tiles.
- Pressure check. If macOS reports critical memory pressure during a job, the job stops.
Quit big apps (VMs, Xcode, lots of browser tabs) before generating on a 64 GB Mac.
Where things live
| What | Where |
|---|---|
| Generated images (+ JSON metadata) | ~/Pictures/ImageGen |
| Models | ~/Library/Application Support/ImageGen/models |
| Python environment | ~/Library/Application Support/ImageGen/venv |
| Engine log | ~/Library/Application Support/ImageGen/engine.log |
Settings (port, Hugging Face token stored in Keychain) are in ImageGen > Settings.
Architecture
ImageGen.app (SwiftUI)
├─ starts ──> Python engine (FastAPI + diffusers on Metal/MPS), 127.0.0.1:7860
│ ├─ /api/* REST API used by the app
│ └─ /mcp MCP server (Streamable HTTP)
└─ polls /api/status for progress, queue and new images
app/SwiftUI app (Swift Package).EngineProcess.swiftrunsuv syncand launches the engine.backend/imagegen/the engine:catalog.py(models),downloader.py(Hugging Face),engine.py(pipeline + job queue),mcp_server.py(MCP tools),app.py(HTTP routes).- One job runs at a time. UI and MCP requests share the same queue.
- The engine listens on
127.0.0.1by default. Nothing is exposed to your network.
Adding a model
Add a ModelSpec to backend/imagegen/catalog.py with the Hugging Face repo and the diffusers pipeline
class name. If the pipeline takes different arguments, adjust Engine._run. Pull requests for new
models are welcome.
Engine development
cd backend
uv run python -m imagegen --port 7860 # the app connects to an engine that is already running
FAQ
Does it work without internet? Yes. You need internet once to download the model and the Python packages. After that, everything runs offline.
Is it a Stable Diffusion or Midjourney alternative? For many uses, yes. Qwen-Image 2.1 is a newer model with very good prompt following and text rendering, and it runs on your own hardware. Check the model license below before using it for client work.
Will it run on 32 GB? Not this model. It needs about 33 GB for the weights alone. Smaller models may be added later.
Intel Macs? No. It needs Apple Silicon and Metal.
License
The ImageGen code is MIT licensed. Use it, fork it, ship it.
The model has its own license. Qwen-Image 2.1 is released by the Qwen team under the Qwen Research License Agreement, which allows non-commercial (research and evaluation) use only. Commercial use needs a separate license from Qwen. ImageGen does not ship the weights. You download them from Hugging Face and accept that license yourself.
Third-party components and their licenses are listed in THIRD_PARTY_NOTICES.md. ImageGen is not affiliated with or endorsed by Alibaba, the Qwen team or Hugging Face.
Credits
Built by Philipp Baldauf. Powered by Qwen-Image, diffusers, PyTorch, FastAPI, the MCP Python SDK and uv.
If ImageGen is useful to you, a star helps other Mac users find it.
ImageGen MCP questions
Does it work without internet?
Yes, once the model and Python packages are downloaded, everything runs offline.
Can I run this on an Intel Mac?
No, the application requires Apple Silicon and Metal support.
Will it run on a Mac with 32 GB of RAM?
No, the Qwen-Image 2.1 model requires approximately 33 GB of memory for the weights alone.
Is it a Stable Diffusion or Midjourney alternative?
It can serve as an alternative for many uses, offering good prompt following and text rendering on your own hardware.