Integration with Google's Gemini 3.1 Flash Image for image generation at multiple resolutions and aspect ratios, and Veo 3 for text-to-video generation with audio, including region repair features.
Integration with OpenAI's GPT Image 2 for high-quality image generation with excellent text rendering, infographics, and diagrams, supporting flexible resolutions and quality levels.
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.
pixel-surgeon-mcp is a multi-provider image generation server. You can use any combination of providers and switch between them per-request:
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'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.
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.
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.
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.
Related MCP server: Nano Banana MCP Server
Tool | Description |
| Text-to-image generation (single image) |
| Parallel batch generation (1-8 images) |
| Text-to-video via Veo 3 with audio (5s or 8s) |
| Edit an existing image with natural language instructions |
| Grid-based tile repair for garbled text (2x2, 3x3, etc.) |
| Targeted region repair with automatic aspect ratio snapping |
| Browser-based crop UI with multi-shot selection |
| List generated images and videos |
| Import an external image into the workspace |
| Remove image background (alpha channel transparency) |
Model | Provider | Resolution | Best for |
| 512 / 1K / 2K / 4K | General image generation, photo-realistic scenes | |
| 1K max (free tier) | Quick drafts, prototyping | |
| OpenAI | Flexible (up to 4K) | Text-heavy images, infographics, diagrams, typography |
| OpenAI | 3 fixed sizes | Legacy support |
| 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.
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.
All generation and edit tools support an optional style parameter:
neo-brutalistMagazine editorial, bold typography, halftone textures. Cream, black, and terracotta palette.
duval-software-infographicDuval Software's signature retro-futurist infographic style. 1960s Space Age meets 1980s arcade. Cathode blue, amber, and salmon palette. Great for diagrams and system overviews.
fractal-arcadeDithered fractals, Sierpinski patterns, low-poly. CRT retro, Amiga/EGA palette.
clean-tech-infographicTechnical diagrams, system flows, data pipelines. Dark navy, cyan, and electric blue.
You need at least one provider API key. You can use any combination for maximum flexibility.
Go to Google AI Studio
Sign in with your Google account
Click Create API Key and copy it
Prepayment required. Gemini 3.1 Flash Image and Veo 3 require billing and prepaid credits. The free-tier fallback (2.5 Flash) has limited resolution and rate limits. See Google AI pricing.
Go to OpenAI API
Sign in or create an account
Click Create new secret key and copy it
Ensure you have API credits — image generation is billed per request
GPT Image 2 excels at text rendering, infographics, and diagrams. If you primarily need text-heavy images, this is the provider to use.
Go to xAI Console
Sign in or create an account
Create an API key and copy it
Grok Imagine is the fastest and cheapest provider. Great for rapid iteration and prototyping. Fixed output resolutions (~1K) with no size control.
No install needed — run directly with npx. Pass whichever API keys you have:
npx pixel-surgeon-mcpclaude mcp add pixel-surgeon \
-e GOOGLE_API_KEY=your-google-key \
-e OPENAI_API_KEY=your-openai-key \
-e XAI_API_KEY=your-xai-key \
-- npx pixel-surgeon-mcp{
"mcpServers": {
"pixel-surgeon": {
"command": "npx",
"args": ["pixel-surgeon-mcp"],
"env": {
"GOOGLE_API_KEY": "your-google-api-key",
"OPENAI_API_KEY": "your-openai-api-key",
"XAI_API_KEY": "your-xai-api-key"
}
}
}
}If you prefer a local clone:
git clone https://github.com/j-east/pixel-surgeon-mcp.git
cd pixel-surgeon-mcp
npm install
npm run buildGenerated images are saved to ~/Pictures/pixel-surgeon/. A local browser viewer auto-launches on first use for full-resolution previews with model selection, respin controls, and search.
npm run dev # tsx watch mode
npm run build # compile TypeScript
npm run start # run compiled serverAspect ratio snapping — crops are adjusted to the nearest Gemini-supported ratio while preserving center point
Histogram matching — per-channel RGB normalization ensures composited regions blend seamlessly
Human-in-the-loop — interactive_fix opens a browser crop UI, blocks via Promise until the user submits, fires parallel Gemini calls, and lets the user pick the best result
MCP size limits — full-resolution images are saved to disk; downsampled versions (< 950KB) are returned in MCP responses
PRs are welcome! We're especially looking for:
Add entries to the STYLE_PRESETS object in src/index.ts. Your PR should include:
The preset definition (name, prompt prefix, default aspect ratio)
2-3 example images generated with the preset (drop them in your PR description)
A short description of the visual style for the README table
The server currently supports Gemini, OpenAI, Grok Imagine, and Veo 3. We'd love adapters for other image/video generation APIs — Stable Diffusion, Flux, etc. If you're interested in adding one, open an issue first so we can align on the interface.
pixel-surgeon-mcp is maintained by John Evans, part of the engineering team at Duval Software — a software engineering firm in Jacksonville Beach, FL building AI-powered tools and custom integrations. If you need MCP servers, AI pipelines, or production tooling built, get in touch.
MIT
Edit an existing image. Supports Gemini and OpenAI models — pass the model param to choose. Provide the filename of an image in /root/Pictures/pixel-surgeon (use list_images to see available files, or save_image to import one first). The MCP reads the file directly — do NOT pass base64 image data.
Inputs: prompt (required), filename (required), aspect_ratio, image_size, +2 more.
Fix an image that has glitched or garbled text by splitting it into tiles, re-rendering each tile, and stitching them back together. This works because smaller sections have less text for the model to handle at once. Use this when a generated image has text artifacts or overloaded text regions.
Inputs: filename (required), prompt, grid, image_size, +1 more.
Fix a specific region of an image by cropping it out, sending it for repair, and reinserting it. The crop is automatically snapped to the nearest supported aspect ratio. Use this when only part of an image has glitched text or artifacts — more precise than fix_image's grid approach.
Inputs: filename (required), x (required), y (required), width (required), +4 more.
Generate a single image. Supports Gemini and OpenAI models — pass the model param to choose. Full-resolution image is viewable in the browser viewer.
Inputs: prompt (required), aspect_ratio, image_size, style, +1 more.
Generate multiple images in parallel. Supports Gemini and OpenAI models — pass the model param to choose. Returns the generated images and any accompanying text. Full-resolution images are viewable in the browser viewer.
Inputs: prompts (required), aspect_ratio, image_size, style, +1 more.
Generate a video using Google's Veo 3. Returns an MP4 video file. Video generation takes 1-3 minutes — the tool will poll until complete. Veo 3 generates both video and ambient audio. Videos are saved to the shared directory and viewable in the browser viewer.
Inputs: prompt (required), aspect_ratio, duration.
Opens an image in a browser-based crop tool where the user can draw a rectangle around the region to fix, add notes/instructions, and submit. The tool waits for the user's selection, then sends the cropped region for repair and composites it back into the original image. Best for precise, user-guided fixes.
Inputs: filename (required), image_size, model.
List image and video files in the shared pixel-surgeon directory (/root/Pictures/pixel-surgeon). Use this to find images available for editing.
Inputs: no named parameters.
Remove a background color from an image and make it transparent. Outputs a PNG with alpha channel. The image must already exist in /root/Pictures/pixel-surgeon (use save_image to import first).
Inputs: filename (required), color, threshold.
Copy an image file into the shared pixel-surgeon directory (/root/Pictures/pixel-surgeon) so it can be used with edit_image. Use this when the user wants to edit an image that exists elsewhere on their filesystem.
Inputs: source_path (required).
Convert a raster image to SVG using potrace vectorization. Best for line art, diagrams, logos, and high-contrast images. The image must already exist in /root/Pictures/pixel-surgeon (use save_image to import first).
Inputs: filename (required), threshold, invert, turdsize.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 11 tools
Each tool has a clearly distinct purpose: generate vs edit vs fix vs background removal vs vectorization. The three fix tools are differentiated by scope (whole image, automatic region, interactive region). No ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., generate_image, remove_background, trace_to_svg). No mixed conventions or vague verbs.
11 tools cover the core image manipulation workflow: import, list, generate, edit, fix, background removal, vectorization, video generation. Well-scoped without being overwhelming.
Covers major AI-driven image operations. Lacks a dedicated manual crop tool (fix_region's automatic snapping may not suffice) and non-AI utilities like resize or filter, but the set is strong for its domain.
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
Generate and upscale AI images, videos and audio.
AI image, video & music generation. Flux, Veo 3.1, Suno V5. Free tier included.
Generate, extend and edit AI images and videos, then assemble clips on a timeline and render.
