pixel-surgeon

pixel-surgeon-mcp

用于 AI 图像和视频生成、编辑以及移植级区域修复的 MCP 服务
由 Gemini 3.1 Flash Image、OpenAI GPT Image 2、Grok Imagine 和 Veo 3 提供支持

---

一个 MCP 服务，让 Claude（或任何 MCP 客户端）能够通过自然语言生成图像、编辑图像、修复乱码文本并创建视频。

工作原理

pixel-surgeon-mcp 是一个多提供商图像生成服务。你可以组合使用任意提供商，并针对每个请求切换提供商：

Gemini（Google）——均衡之选

Google 的图像生成流程采用两阶段方案：先由 Gemini 3.1 Pro 理解你的提示词，再由 Gemini 3.1 Flash Image 渲染像素。支持 9 种宽高比，分辨率为 512/1K/2K/4K。性价比出色，并提供免费套餐。

OpenAI GPT Image 2 ——最高品质

OpenAI 最新的图像模型，大幅提升了文本渲染和视觉保真度。支持灵活分辨率——pixel-surgeon 会自动将你选择的尺寸和宽高比映射为最佳像素尺寸。质量级别：medium（快速）和 high（可用于印刷）。特别适合信息图、示意图和文本密集型图像，而其他模型在这些场景中往往表现不佳。速度较慢，成本较高。

Grok Imagine（xAI）——速度最快

xAI 的 Aurora 驱动图像模型。生成速度最快，成本最低。支持 7 种宽高比，分辨率固定（约 1K）。适合快速原型制作和迭代。

Veo 3（视频）

生成视频时，服务会通过异步轮询调用 Veo 3，生成视频和环境音频。支持 16:9 和 9:16，时长为 5s 或 8s。

区域修复

AI 图像模型难以处理文本密集型图像。修复工具通过将较小区域发送给提供商来解决这个问题，然后使用直方图匹配合成将结果拼接回去，实现无缝融合。

工具

工具	描述
generate_image	文生图（单张图像）
generate_images	并行批量生成（1-8 张图像）
generate_video	通过 Veo 3 生成带音频的视频（5s 或 8s）
edit_image	根据自然语言指令编辑现有图像
fix_image	基于网格的分块修复，用于修复乱码文本（2x2、3x3 等）
fix_region	定向区域修复，自动调整至合适的宽高比
interactive_fix	基于浏览器的裁剪界面，支持多镜头选择
list_images	列出生成的图像和视频
save_image	将外部图像导入工作区
remove_background	移除图像背景（Alpha 通道透明度）

模型

模型	提供方	分辨率	适用场景
gemini-3.1-flash-image	Google	512 / 1K / 2K / 4K	通用图像生成、写实场景
gemini-2.5-flash-image	Google	最高 1K（免费层级）	快速草稿、原型设计
gpt-image-2	OpenAI	灵活（最高 4K）	文本密集型图像、信息图、图表、排版
gpt-image-1	OpenAI	3 种固定尺寸	旧版支持
grok-imagine	xAI	固定（每种比例约 1K）	快速迭代、成本最低

通过 model 工具参数在单次调用中指定模型，或设置 DEFAULT_IMAGE_MODEL 环境变量。

Gemini 自动回退

如果 Gemini 生成调用因结算／预付费错误而失败，服务会自动重试免费层级的 gemini-2.5-flash-image 模型。发生这种情况时，查看器会显示黄色横幅。免费层级限制：最高 1K 分辨率、每分钟 10 次请求、每天 500 次请求。

风格预设

所有生成和编辑工具都支持可选的 style 参数：

neo-brutalist

杂志编辑风格、粗体排版、半色调纹理。奶油色、黑色和陶土色调。

duval-software-infographic

Duval Software 的标志性复古未来主义信息图风格。融合 1960 年代太空时代与 1980 年代街机风格。阴极蓝、琥珀色和鲑鱼色调。适用于图表和系统概览。

fractal-arcade

抖动分形、谢尔宾斯基图案、低多边形。CRT 复古风格，采用 Amiga/EGA 配色。

clean-tech-infographic

技术图表、系统流程、数据管道。深海军蓝、青色和亮电蓝。

设置

获取 API 密钥

你至少需要一个提供方的 API 密钥。你可以组合使用任意数量的密钥，以获得最大灵活性。

Google（Gemini + Veo 3）

1. 前往 Google AI Studio
2. 使用你的 Google 账号登录
3. 点击 Create API Key 并复制密钥

需要预付费。 Gemini 3.1 Flash Image 和 Veo 3 需要启用结算并预付额度。免费层级回退模型（2.5 Flash）的分辨率和速率均有限制。请参阅 Google AI 定价。

OpenAI（GPT Image 2）

1. 前往 OpenAI API
2. 登录或创建账号
3. 点击 Create new secret key 并复制密钥
4. 确保你的 API 账户有额度——图像生成按请求计费

GPT Image 2 擅长渲染文本、生成信息图和图表。如果你主要需要生成文本密集型图像，请使用此提供方。

xAI（Grok Imagine）

1. 前往 xAI Console
2. 登录或创建账号
3. 创建 API 密钥并复制

Grok Imagine 是速度最快、价格最低的提供方。非常适合快速迭代和原型设计。输出分辨率固定（约 1K），无法控制尺寸。

快速开始（npx）

无需安装——直接通过 npx 运行。传入你已有的任意 API 密钥：

npx pixel-surgeon-mcp

Claude Code CLI

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 客户端配置

{
  "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"
      }
    }
  }
}

从源代码安装

如果你倾向于本地克隆：

git clone https://github.com/j-east/pixel-surgeon-mcp.git
cd pixel-surgeon-mcp
npm install
npm run build

图像输出

生成的图像会保存到 ~/Pictures/pixel-surgeon/。首次使用时会自动启动本地浏览器查看器，可查看全分辨率预览，并使用模型选择、重新生成控制和搜索功能。

开发

npm run dev    # tsx watch mode
npm run build  # compile TypeScript
npm run start  # run compiled server

关键实现细节

• 宽高比吸附 — 在保留中心点的同时，将裁剪调整为最接近的 Gemini 支持的宽高比
• 直方图匹配 — 对 RGB 各通道进行归一化，确保合成区域无缝融合
• Human-in-the-loop — interactive_fix 会打开浏览器裁剪界面，通过 Promise 阻塞，直到用户提交；随后并行调用 Gemini，并让用户挑选最佳结果
• MCP 大小限制 — 全分辨率图像会保存到磁盘；下采样版本（< 950KB）会在 MCP 响应中返回

贡献

欢迎提交 PR！我们尤其期待：

新增风格预设

在 src/index.ts 的 STYLE_PRESETS 对象中添加条目。你的 PR 应包含：

• 预设定义（名称、提示词前缀、默认宽高比）
• 使用该预设生成的 2-3 张示例图像（请附在 PR 描述中）
• README 表格中对视觉风格的简短描述

模型适配器

该服务目前支持 Gemini、OpenAI、Grok Imagine 和 Veo 3。我们期待支持其他图像/视频生成 API 的适配器，例如 Stable Diffusion、Flux 等。如果你有兴趣添加适配器，请先提交 issue，以便我们就接口达成一致。

由 Duval Software 构建

pixel-surgeon-mcp 由 John Evans 维护，他是 Duval Software 工程团队的一员。Duval Software 是一家位于佛罗里达州 Jacksonville Beach 的软件工程公司，致力于构建 AI 驱动的工具和定制集成。如果你需要构建 MCP 服务、AI 流水线或生产级工具，欢迎联系我们。

许可证

MIT