j-east/pixel-surgeon-mcp

MCP server for AI image & video generation, editing, and transplant-grade region repair
Powered by Gemini 3.1 Flash Image, OpenAI GPT Image 2, Grok Imagine, and Veo 3
---
An MCP server that gives Claude (or any MCP client) the ability to generate images, edit them, fix garbled text, and create videos — all through natural language.
How it works
pixel-surgeon-mcp is a **multi-provider** image generation server. You can use any combination of providers and switch between them per-request:
Gemini (Google) — balanced
Google's image generation pipeline uses a two-stage approach: **Gemini 3.1 Pro** reasons about your prompt, then **Gemini 3.1 Flash Image** renders the pixels. Supports 9 aspect ratios at 512/1K/2K/4K resolution. Best price/performance ratio, with a free tier available.
OpenAI GPT Image 2 — highest quality
OpenAI's latest image model with dramatically improved text rendering and visual fidelity. Supports flexible resolutions — pixel-surgeon maps your chosen size and aspect ratio to the optimal pixel dimensions automatically. Quality levels: medium (fast) and high (print-ready). **Excellent for infographics, diagrams, and text-heavy images** where other models struggle. Slower and more expensive.
Grok Imagine (xAI) — fastest
xAI's Aurora-powered image model. Fastest generation speed and lowest cost. Supports 7 aspect ratios at fixed resolutions (~1K). Good for rapid prototyping and iteration.
Veo 3 (Video)
For video, the server calls **Veo 3** with async polling — generating both video and ambient audio. Supports 16:9 and 9:16 at 5s or 8s duration.
Region repair
AI image models struggle with text-heavy images. The fix tools solve this by sending smaller regions to the provider, then stitching the results back with histogram-matched compositing for seamless blending.
Tools
| Tool | Description |
|------|-------------|
| generate_image | Text-to-image generation (single image) |
| generate_images | Parallel batch generation (1-8 images) |
| generate_video | Text-to-video via Veo 3 with audio (5s or 8s) |
| edit_image | Edit an existing image with natural language instructions |
| fix_image | Grid-based tile repair for garbled text (2x2, 3x3, etc.) |
| fix_region | Targeted region repair with automatic aspect ratio snapping |
| interactive_fix | Browser-based crop UI with multi-shot selection |
| list_images | List generated images and videos |
| save_image | Import an external image into the workspace |
| remove_background | Remove image background (alpha channel transparency) |
Models
| Model | Provider | Resolution | Best for |
|-------|----------|-----------|----------|
| gemini-3.1-flash-image | Google | 512 / 1K / 2K / 4K | General image generation, photo-realistic scenes |
| gemini-2.5-flash-image | Google | 1K max (free tier) | Quick drafts, prototyping |
| gpt-image-2 | OpenAI | Flexible (up to 4K) | Text-heavy images, infographics, diagrams, typography |
| gpt-image-1 | OpenAI | 3 fixed sizes | Legacy support |
| grok-imagine | xAI | Fixed (~1K per ratio) | Fast iteration, lowest cost |
Force a specific model per-call via the model tool parameter, or set DEFAULT_IMAGE_MODEL env var.
Gemini automatic fallback
If a Gemini generation call fails with a billing / prepay error, the server automatically retries on the free-tier **gemini-2.5-flash-image** model. The viewer shows a yellow banner when this happens. Free-tier limits: 1K max resolution, 10 RPM, 500 RPD.