{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/architecture.png\" alt=\"pixel-surgeon-mcp architecture\" width=\"800\" />\n</p>\n\n<h1 align=\"center\">pixel-surgeon-mcp</h1>\n\n<p align=\"center\">\n  <strong>MCP server for AI image &amp; video generation, editing, and transplant-grade region repair</strong><br/>\n  Powered by Gemini 3.1 Flash Image, OpenAI GPT Image 2, Grok Imagine, and Veo 3\n</p>\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/badge/MCP-stdio-blue\" alt=\"MCP stdio\" />\n  <img src=\"https://img.shields.io/badge/Gemini_3.1-Flash_Image-4285F4?logo=google\" alt=\"Gemini\" />\n  <img src=\"https://img.shields.io/badge/GPT_Image_2-OpenAI-412991?logo=openai&logoColor=white\" alt=\"OpenAI\" />\n  <img src=\"https://img.shields.io/badge/Grok_Imagine-xAI-000000?logo=x&logoColor=white\" alt=\"Grok\" />\n  <img src=\"https://img.shields.io/badge/Veo_3-Video-34A853?logo=google\" alt=\"Veo 3\" />\n  <img src=\"https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white\" alt=\"TypeScript\" />\n</p>\n\n---\n\nAn [MCP](https://modelcontextprotocol.io) 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.\n\n## How it works\n\npixel-surgeon-mcp is a **multi-provider** image generation server. You can use any combination of providers and switch between them per-request:\n\n### Gemini (Google) — balanced\n\nGoogle'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.\n\n### OpenAI GPT Image 2 — highest quality\n\nOpenAI'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.\n\n### Grok Imagine (xAI) — fastest\n\nxAI'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.\n\n### Veo 3 (Video)\n\nFor 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.\n\n### Region repair\n\nAI 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.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `generate_image` | Text-to-image generation (single image) |\n| `generate_images` | Parallel batch generation (1-8 images) |\n| `generate_video` | Text-to-video via Veo 3 with audio (5s or 8s) |\n| `edit_image` | Edit an existing image with natural language instructions |\n| `fix_image` | Grid-based tile repair for garbled text (2x2, 3x3, etc.) |\n| `fix_region` | Targeted region repair with automatic aspect ratio snapping |\n| `interactive_fix` | Browser-based crop UI with multi-shot selection |\n| `list_images` | List generated images and videos |\n| `save_image` | Import an external image into the workspace |\n| `remove_background` | Remove image background (alpha channel transparency) |\n\n## Models\n\n| Model | Provider | Resolution | Best for |\n|-------|----------|-----------|----------|\n| `gemini-3.1-flash-image` | Google | 512 / 1K / 2K / 4K | General image generation, photo-realistic scenes |\n| `gemini-2.5-flash-image` | Google | 1K max (free tier) | Quick drafts, prototyping |\n| `gpt-image-2` | OpenAI | Flexible (up to 4K) | Text-heavy images, infographics, diagrams, typography |\n| `gpt-image-1` | OpenAI | 3 fixed sizes | Legacy support |\n| `grok-imagine` | xAI | Fixed (~1K per ratio) | Fast iteration, lowest cost |\n\nForce a specific model per-call via the `model` tool parameter, or set `DEFAULT_IMAGE_MODEL` env var.\n\n### Gemini automatic fallback\n\nIf 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.\n\n## Style presets\n\nAll generation and edit tools support an optional `style` parameter:\n\n### `neo-brutalist`\nMagazine editorial, bold typography, halftone textures. Cream, black, and terracotta palette.\n\n<img src=\"assets/style-neo-brutalist.png\" alt=\"neo-brutalist style example\" width=\"400\" />\n\n### `duval-software-infographic`\nDuval 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.\n\n<img src=\"assets/style-neo-retro-futurism.png\" alt=\"duval-software-infographic style example\" width=\"400\" />\n\n### `fractal-arcade`\nDithered fractals, Sierpinski patterns, low-poly. CRT retro, Amiga/EGA palette.\n\n<img src=\"assets/style-fractal-arcade.png\" alt=\"fractal-arcade style example\" width=\"400\" />\n\n### `clean-tech-infographic`\nTechnical diagrams, system flows, data pipelines. Dark navy, cyan, and electric blue.\n\n<img src=\"assets/style-clean-tech-infographic.png\" alt=\"clean-tech-infographic style example\" width=\"600\" />\n\n## Setup\n\n### Get your API key(s)\n\nYou need at least one provider API key. You can use any combination for maximum flexibility.\n\n#### Google (Gemini + Veo 3)\n\n1. Go to [Google AI Studio](https://aistudio.google.com/apikey)\n2. Sign in with your Google account\n3. Click **Create API Key** and copy it\n\n> **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](https://ai.google.dev/pricing).\n\n#### OpenAI (GPT Image 2)\n\n1. Go to [OpenAI API](https://platform.openai.com/api-keys)\n2. Sign in or create an account\n3. Click **Create new secret key** and copy it\n4. Ensure you have API credits — image generation is billed per request\n\n> GPT Image 2 excels at text rendering, infographics, and diagrams. If you primarily need text-heavy images, this is the provider to use.\n\n#### xAI (Grok Imagine)\n\n1. Go to [xAI Console](https://console.x.ai/)\n2. Sign in or create an account\n3. Create an API key and copy it\n\n> Grok Imagine is the fastest and cheapest provider. Great for rapid iteration and prototyping. Fixed output resolutions (~1K) with no size control.\n\n### Quick start (npx)\n\nNo install needed — run directly with npx. Pass whichever API keys you have:\n\n```bash\nnpx pixel-surgeon-mcp\n```\n\n#### Claude Code CLI\n\n```bash\nclaude mcp add pixel-surgeon \\\n  -e GOOGLE_API_KEY=your-google-key \\\n  -e OPENAI_API_KEY=your-openai-key \\\n  -e XAI_API_KEY=your-xai-key \\\n  -- npx pixel-surgeon-mcp\n```\n\n#### Claude Desktop / MCP client config\n\n```json\n{\n  \"mcpServers\": {\n    \"pixel-surgeon\": {\n      \"command\": \"npx\",\n      \"args\": [\"pixel-surgeon-mcp\"],\n      \"env\": {\n        \"GOOGLE_API_KEY\": \"your-google-api-key\",\n        \"OPENAI_API_KEY\": \"your-openai-api-key\",\n        \"XAI_API_KEY\": \"your-xai-api-key\"\n      }\n    }\n  }\n}\n```\n\n### Install from source\n\nIf you prefer a local clone:\n\n```bash\ngit clone https://github.com/j-east/pixel-surgeon-mcp.git\ncd pixel-surgeon-mcp\nnpm install\nnpm run build\n```\n\n### Image output\n\nGenerated 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.\n\n## Development\n\n```bash\nnpm run dev    # tsx watch mode\nnpm run build  # compile TypeScript\nnpm run start  # run compiled server\n```\n\n## Key implementation details\n\n- **Aspect ratio snapping** — crops are adjusted to the nearest Gemini-supported ratio while preserving center point\n- **Histogram matching** — per-channel RGB normalization ensures composited regions blend seamlessly\n- **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\n- **MCP size limits** — full-resolution images are saved to disk; downsampled versions (< 950KB) are returned in MCP responses\n\n## Contributing\n\nPRs are welcome! We're especially looking for:\n\n### New style presets\n\nAdd entries to the `STYLE_PRESETS` object in `src/index.ts`. Your PR should include:\n\n- The preset definition (name, prompt prefix, default aspect ratio)\n- 2-3 example images generated with the preset (drop them in your PR description)\n- A short description of the visual style for the README table\n\n### Model adapters\n\nThe 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.\n\n## Built by Duval Software\n\npixel-surgeon-mcp is maintained by [John Evans](https://github.com/j-east), part of the engineering team at [Duval Software](https://duvalsoftware.com) — 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](https://duvalsoftware.com).\n\n## License\n\nMIT\n",
  "bytes": 9446,
  "sha": "5f2d79d3d71e70313b57873b6de8009f77f50fee912f0ec877f5acaf32e2ed30",
  "repo_slug": "j-east/pixel-surgeon-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_j_east_pixel_surgeon_86acdf23/readme"
}