# j-east/pixel-surgeon-mcp [Health: Active]

**Category:** 🎨 Art & Culture  
**Repository:** https://github.com/j-east/pixel-surgeon-mcp  
**GitHub Stars:** 5  
**npm Downloads (last month):** 211  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/j-east-pixel-surgeon-mcp

## Description
AI image and video generation, editing, and transplant-grade region repair. Multi-provider (Gemini 3.1 Flash Image, GPT Image 2, Grok Imagine, Veo 3), 9 tools, 4 style presets, grid-based and interactive crop repair. npx pixel-surgeon-mcp

## Tools
Capabilities this server exposes over MCP:

- **list_images** — List image and video files in the shared pixel-surgeon directory (/home/user/Pictures/pixel-surgeon). Use this to find images available for editing.
- **save_image** — Copy an image file into the shared pixel-surgeon directory (/home/user/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.
- **generate_images** — 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.
- **generate_image** — Generate a single image. Supports Gemini and OpenAI models — pass the model param to choose. Full-resolution image is viewable in the browser viewer.
- **generate_video** — 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.
- **edit_image** — Edit an existing image. Supports Gemini and OpenAI models — pass the model param to choose. Provide the filename of an image in /home/user/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.
- **fix_image** — 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.
- **fix_region** — 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.
- **interactive_fix** — 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.
- **remove_background** — Remove a background color from an image and make it transparent. Outputs a PNG with alpha channel. The image must already exist in /home/user/Pictures/pixel-surgeon (use save_image to import first).
- **trace_to_svg** — 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 /home/user/Pictures/pixel-surgeon (use save_image to import first).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "pixel-surgeon-mcp": {
    "command": "npx",
    "args": ["-y","pixel-surgeon-mcp"],
    "env": {
      "GOOGLE_API_KEY": "",
      "OPENAI_API_KEY": "",
      "XAI_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `GOOGLE_API_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What j-east/pixel-surgeon-mcp MCP server does

j-east/pixel-surgeon-mcp MCP server exposes image and video workflows through MCP tools. It can generate one image or a parallel batch, edit an existing workspace image from natural-language instructions, create a Veo 3 video, and repair visual defects. Additional utilities import files into the workspace, list available media, remove a background color with transparency, and convert raster artwork to SVG.

The repair tools target different levels of precision. `fix_image` divides an image into tiles, re-renders the tiles, and stitches them together to address garbled text or broader artifacts. `fix_region` crops a selected area and reinserts the repaired result. `interactive_fix` opens a browser crop tool so a person can select the exact region and add repair instructions.

## How it works

j-east/pixel-surgeon-mcp MCP server uses a multi-provider model setup. Image generation and editing can use Google Gemini or OpenAI image models, with a `model` parameter available for choosing a model. Video generation uses Google Veo 3 and polls until the MP4 is ready; the result includes ambient audio and is saved in the shared directory.

Crops are adjusted to the nearest supported aspect ratio before repair. Repaired regions are composited with histogram matching to normalize RGB channels. Full-resolution outputs remain on disk, while smaller versions can be returned in MCP responses to stay within MCP message-size limits. Generated media can be viewed through the local browser viewer.

## Setup and configuration

Run the package without a local installation:

```bash
npx pixel-surgeon-mcp
```

At least one provider API key is needed. The supported environment variables are `GOOGLE_API_KEY`, `OPENAI_API_KEY`, and `XAI_API_KEY`; supply the keys for the providers you plan to use. Google credentials cover Gemini and Veo 3, OpenAI credentials cover GPT Image models, and xAI credentials cover Grok Imagine.

Claude Code can register the server with `claude mcp add` and environment variables. Claude Desktop and other MCP clients can start it with the `npx` command and an MCP server configuration. A source-based setup is also available by cloning the repository, running `npm install`, and building with `npm run build`.

Images and videos are stored in `~/Pictures/pixel-surgeon/`. To edit or process a file elsewhere, call `save_image` first. `list_images` shows media already available in that directory.

## Tools and capabilities

The j-east/pixel-surgeon-mcp MCP server provides these operations:

- `generate_image` creates one image.
- `generate_images` creates multiple images in parallel.
- `generate_video` creates a 5- or 8-second Veo 3 video.
- `edit_image` applies natural-language changes to a workspace image.
- `fix_image`, `fix_region`, and `interactive_fix` repair text artifacts or other damaged areas.
- `list_images` and `save_image` manage workspace files.
- `remove_background` outputs a transparent PNG after removing a background color.
- `trace_to_svg` vectorizes suitable raster art with potrace.

Generation and editing tools support optional style presets, including neo-brutalist, duval-software-infographic, fractal-arcade, and clean-tech-infographic.

## Limitations and notes

Video generation can take one to three minutes because the server waits for Veo 3 to finish. Veo 3 supports 16:9 and 9:16 output at 5 or 8 seconds. Grok Imagine uses fixed, approximately 1K resolutions, while Gemini and OpenAI models provide different resolution options.

The Google free-tier fallback uses Gemini 2.5 Flash Image after certain billing or prepayment failures, but it is limited to 1K resolution, 10 requests per minute, and 500 requests per day. Google Gemini 3.1 Flash Image and Veo 3 require billing and prepaid credits. Files passed to `edit_image`, `remove_background`, and `trace_to_svg` must already exist in the shared directory; do not pass base64 data to `edit_image`.

_Full upstream README: https://allmcps.com/mcp/j-east-pixel-surgeon-mcp/readme_