Pixel Surgeon

io.github.j-eastPublished by GitHub account j-eastv1.1.1Updated Oct 24, 2026

AI image and video generation, editing, and region repair via Gemini, OpenAI, and Grok.

VerifiedSTDIODesktop onlyMedia & DesignAI & ML

Overview

AI-generated overview

A local MCP server that lets an assistant generate, edit and repair images and create short videos through Gemini, OpenAI and xAI models.

What you can do
Generate single or batch images from text prompts, with optional style presets and per-call model choice across Gemini, GPT Image and Grok Imagine models, plus text-to-video with audio via Veo 3 at 5 or 8 seconds. Edit existing images with natural-language instructions, or repair garbled text and specific regions using grid tiles and targeted crops with automatic aspect-ratio snapping and histogram-matched compositing. Open a browser crop interface for human-in-the-loop region selection and multi-shot comparison. Manage the local workspace by listing generated images and videos, importing external images, and removing backgrounds to alpha transparency.
When to use it
Useful when you want an assistant to produce or touch up visuals in conversation: drafts and prototypes, text-heavy infographics and diagrams, or fixing garbled text in an existing image. Also suited to short promotional or ambient video clips and quick background removal.
Requirements
Runs locally via npx (Node.js) or from a source clone. At least one provider API key is needed, passed as GOOGLE_API_KEY, OPENAI_API_KEY or XAI_API_KEY; any combination works. Google image and Veo 3 use requires billing and prepaid credits. Output is saved under the user's Pictures folder and a local browser viewer launches on first use.
Before you install
Each provider key is a billable credential and image or video generation is charged per request; Google's premium models need prepaid credits, and the server silently falls back to a free-tier Gemini model on billing errors. Generated files are written to the local Pictures folder and a browser viewer opens automatically. Prompts and source images are sent to the chosen third-party provider.

Installation

In SourceWeft

  1. Open Pixel Surgeon in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[pixel-surgeon-mcp architecture]

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

[MCP stdio] [Gemini] [OpenAI] [Grok] [Veo 3] [TypeScript]

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

ToolDescription
generate_imageText-to-image generation (single image)
generate_imagesParallel batch generation (1-8 images)
generate_videoText-to-video via Veo 3 with audio (5s or 8s)
edit_imageEdit an existing image with natural language instructions
fix_imageGrid-based tile repair for garbled text (2x2, 3x3, etc.)
fix_regionTargeted region repair with automatic aspect ratio snapping
interactive_fixBrowser-based crop UI with multi-shot selection
list_imagesList generated images and videos
save_imageImport an external image into the workspace
remove_backgroundRemove image background (alpha channel transparency)

Models

ModelProviderResolutionBest for
gemini-3.1-flash-imageGoogle512 / 1K / 2K / 4KGeneral image generation, photo-realistic scenes
gemini-2.5-flash-imageGoogle1K max (free tier)Quick drafts, prototyping
gpt-image-2OpenAIFlexible (up to 4K)Text-heavy images, infographics, diagrams, typography
gpt-image-1OpenAI3 fixed sizesLegacy support
grok-imaginexAIFixed (~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.

Style presets

All generation and edit tools support an optional style parameter:

neo-brutalist

Magazine editorial, bold typography, halftone textures. Cream, black, and terracotta palette.

[neo-brutalist style example]

duval-software-infographic

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

[duval-software-infographic style example]

fractal-arcade

Dithered fractals, Sierpinski patterns, low-poly. CRT retro, Amiga/EGA palette.

[fractal-arcade style example]

clean-tech-infographic

Technical diagrams, system flows, data pipelines. Dark navy, cyan, and electric blue.

[clean-tech-infographic style example]

Setup

Get your API key(s)

You need at least one provider API key. You can use any combination for maximum flexibility.

Google (Gemini + Veo 3)
  1. Go to Google AI Studio
  2. Sign in with your Google account
  3. 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.

OpenAI (GPT Image 2)
  1. Go to OpenAI API
  2. Sign in or create an account
  3. Click Create new secret key and copy it
  4. 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.

xAI (Grok Imagine)
  1. Go to xAI Console
  2. Sign in or create an account
  3. 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.

Quick start (npx)

No install needed — run directly with npx. Pass whichever API keys you have:

bash
npx pixel-surgeon-mcp
Claude Code CLI
bash
claude 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
Claude Desktop / MCP client config
json
{  "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"      }    }  }}

Install from source

If you prefer a local clone:

bash
git clone https://github.com/j-east/pixel-surgeon-mcp.gitcd pixel-surgeon-mcpnpm installnpm run build

Image output

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

Development

bash
npm run dev    # tsx watch modenpm run build  # compile TypeScriptnpm run start  # run compiled server

Key implementation details

  • Aspect 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

Contributing

PRs are welcome! We're especially looking for:

New style presets

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

Model adapters

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.

Built by Duval Software

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.

License

MIT

Source: README.md at commit a7c9189

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.1.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts