pixel-surgeon — Claude Code MCP server: what it does, how to install
Generate and edit AI images or video clips directly inside your agent workflow via Gemini, OpenAI, and Grok. Fixes mangled text through region patching.
claude mcp add pixel-surgeon -e GOOGLE_API_KEY=<GOOGLE_API_KEY> -e OPENAI_API_KEY=<OPENAI_API_KEY> -e XAI_API_KEY=<XAI_API_KEY> -- npx -y pixel-surgeon-mcpWhat pixel-surgeon does
The server connects your coding agent to three external model providers. Grok Imagine handles quick concept drafts at minimal expense. When an asset needs crisp typography or clear diagrams, requests go to OpenAI gpt-image-2. Google Veo 3 builds short video clips. It creates ambient audio along with footage at 5s or 8s durations.
Standard image generators often mangle letters and small details. To address this, tools like fix_image divide pictures into tile grids to re-render broken text regions before stitching them back together. There is also remove_background for alpha transparency and built-in visual presets such as neo-brutalist and duval-software-infographic.
Running the server requires at least one API credential among Google, OpenAI, or xAI. Advanced models like Gemini 3.1 Flash Image and Veo 3 demand prepaid Google AI credits. When a Google billing error occurs, the server drops down to the free gemini-2.5-flash-image tier capped at 1K resolution.
What it helps with
- generate infographics and diagrams with legible typography using GPT Image 2
- repair garbled letters on generated graphics via grid tile re-rendering
- render short video clips with matching audio using Veo 3
- strip backgrounds from images to produce transparent alpha channels
Example prompts for the agent
- Generate a system architecture diagram in clean-tech-infographic style using gpt-image-2
- Repair the illegible labels on this diagram using fix_image
- Create a 5-second vertical 9:16 video clip from this prompt using Veo 3
How to install pixel-surgeon
Platform CLI
claude mcp add pixel-surgeon -e GOOGLE_API_KEY=<GOOGLE_API_KEY> -e OPENAI_API_KEY=<OPENAI_API_KEY> -e XAI_API_KEY=<XAI_API_KEY> -- npx -y pixel-surgeon-mcpReplace <…> with your own values
Platform CLI
codex mcp add pixel-surgeon --env GOOGLE_API_KEY=<GOOGLE_API_KEY> --env OPENAI_API_KEY=<OPENAI_API_KEY> --env XAI_API_KEY=<XAI_API_KEY> -- npx -y pixel-surgeon-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"pixel-surgeon": {
"command": "npx",
"args": [
"-y",
"pixel-surgeon-mcp"
],
"env": {
"GOOGLE_API_KEY": "<GOOGLE_API_KEY>",
"OPENAI_API_KEY": "<OPENAI_API_KEY>",
"XAI_API_KEY": "<XAI_API_KEY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"pixel-surgeon": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"pixel-surgeon-mcp"
],
"env": {
"GOOGLE_API_KEY": "<GOOGLE_API_KEY>",
"OPENAI_API_KEY": "<OPENAI_API_KEY>",
"XAI_API_KEY": "<XAI_API_KEY>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e GOOGLE_API_KEY=<GOOGLE_API_KEY> -e OPENAI_API_KEY=<OPENAI_API_KEY> -e XAI_API_KEY=<XAI_API_KEY> pixel-surgeon npx -y pixel-surgeon-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about pixel-surgeon
How do I install pixel-surgeon in Claude Code?
Run `claude mcp add pixel-surgeon -e GOOGLE_API_KEY=<GOOGLE_API_KEY> -e OPENAI_API_KEY=<OPENAI_API_KEY> -e XAI_API_KEY=<XAI_API_KEY> -- npx -y pixel-surgeon-mcp`. You only need to supply the key for whichever provider you plan to use.
What does pixel-surgeon do?
It provides MCP tools for generating images, cutting backgrounds, and rendering short Veo 3 videos. It also patches distorted text on AI images using localized tile repairs.
What happens if Gemini API credits run out?
If a request fails due to Google billing limits, the server falls back to gemini-2.5-flash-image. That fallback tier is free but limits outputs to 1K resolution and 10 requests per minute.
