imaginate-mcp

一个 MCP 服务器，使用 OpenAI GPT Image 和 Google Gemini（Nano Banana）生成和编辑图像。它通过 stdio 运行，将每张图像保存到磁盘，并返回文件路径，这样你的助手就可以继续使用结果。

你能获得什么

六个工具，按提供方划分：

只有你配置了对应密钥的工具才会被注册。如果你只设置了 OPENAI_API_KEY，你的助手只会看到三个工具，而且其中任何一个都不会因为缺少 Google 密钥而失败。这正是按提供方拆分工具、而不是采用一个带 provider 参数的单一工具的主要原因。

Related MCP server: OpenAI Image Generation MCP Server

环境要求

• Node.js 20 或更高版本

• 一个 OpenAI API 密钥、一个 Gemini API 密钥，或者两者都提供

GPT Image 模型需要 OpenAI API 组织验证。如果尚未完成该验证，OpenAI 会拒绝请求，服务器会明确告知你这一点。

连接

使用 npx 运行已发布包。无需克隆仓库，也无需全局安装该包。

npx -y @pinkpixel/imaginate-mcp

将服务器添加到客户端的配置中。对于 Claude Desktop，编辑 claude_desktop_config.json。对于 Claude Code，使用项目中的 .mcp.json 或用户设置。

{
  "mcpServers": {
    "imaginate": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/imaginate-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "GEMINI_API_KEY": "...",
        "IMAGINATE_OUTPUT_DIR": "~/Pictures/imaginate"
      }
    }
  }
}

编辑配置后重启客户端。如果没有出现任何图像工具，请调用 imaginate_setup_help。该工具只会在未找到任何提供方密钥时存在，并列出你仍需设置的变量。

从源码运行

如果你想在本地开发这个服务器，请克隆并构建该仓库：

git clone https://github.com/pinkpixel-dev/imaginate-mcp.git
cd imaginate-mcp
npm install
npm run build
node dist/index.js

要将 MCP 客户端连接到这个构建版本，请使用 "command": "node"，并将 args 设置为 dist/index.js 的绝对路径。

配置

每个变量都会在启动时读取一次，因此修改后请重启客户端。

任何工具调用都可以通过 output_dir 覆盖输出目录，并通过 filename 覆盖文件名。

文件的保存与命名

图像会被保存到输出目录。服务器永远不会覆盖任何文件。如果名为 cat.png 的文件已存在，就会保存为 cat-1.png，然后是 cat-2.png。

默认文件名类似 openai-a-red-fox-20260825-134512-071.png，即提供方前缀、提示词对应 slug 和时间戳。如果你想要特定名称，就传入 filename。

用于编辑的源图像必须是本地文件，且需要传入绝对路径。这些工具不会下载远程 URL，所以如果文件来自网络，请先将其获取到本地。源文件只读，且永远不会被修改。

使用方法

服务器连接完毕后，你大多可以像平常一样与助手对话。但有几件事值得一提。

选择提供方

两个提供方各有优势，只是侧重点不同。

Gemini 在图像内文字、世界知识以及信息图类任务上表现更好，并且可以在开始绘制前结合实时的 Google Search 结果。它还会返回一个交互 ID，因此无需重复上传图像，就能继续打磨同一张图。

GPT Image 能很好地遵循复杂的布局指示，并且对尺寸、质量和背景有精细的控制。当你需要透明背景时应该使用它，不过要达到这一点，你需要 gpt-image-1.5 或更早版本，因为 gpt-image-2 已移除该功能。

在 Gemini 图像上持续迭代

每个 Gemini 结果都包含一个交互 ID。在下次 gemini_edit_image 调用中，把它作为 previous_interaction_id 传回去，并跳过再次发送图像：

1. 用你的提示词调用 demo_generate_image。结果中会包含一个交互 ID。

2. 使用 previous_interaction_id 调用 demo_edit_image，并附上类似“让它变成横版”的提示词。

这比重新上传更划算，也能让各轮之间的图像更一致。

编辑和组合

两个 *_edit_image 工具都通过同一接口处理多种任务。传入一个图像路径，就编辑该图像；传入多个路径，就把它们组合成一个新场景。

在带蒙版的修复上，两家提供方有所不同。OpenAI 需要一个带 alpha 通道的真实蒙版 PNG，通过 mask 传入。Gemini 是语义化修复，只要说“只改天空，其他一切保持不变”即可，无需提供蒙版文件。

参考图像数量上限取决于 Gemini 模型：Lite 为 14、Nano Banana 2 为 10、Pro 为 6。如果不确定，可调用 gemini_list_image_models 查看。

开发

npm run build      # compile to dist/
npm run watch      # compile on change
npm run typecheck  # types only, no output
npm test           # compile tests and run them

测试使用 Node.js 内置的测试运行器。它们覆盖文件命名与保存逻辑、Gemini 响应解析以及错误信息映射。测试不调用任何 API，因此即使没有密钥也可以运行。

布局如下：

src/
  index.ts               entry point, conditional tool registration
  config.ts              environment parsing
  lib/                   file handling, errors, result formatting, model catalog
  providers/openai/      OpenAI client wrapper and tool definitions
  providers/google/      Gemini client wrapper and tool definitions
tests/

限制

• 源图像必须是本地文件。不支持远程 URL。

• 尚未接入流式输出和部分图像。调用会在图像生成完成后才返回。

• Gemini 不能可靠地遵循请求的图像数量，因此每次调用请生成一张图像。OpenAI 工具接受 n 参数，并且工作正常。

• 对复杂提示词，OpenAI 最长可能耗时两分钟。这是 API 本身的开销，与服务器无关。

• 每张 Gemini 图像都带有不可见的 SynthID 水印。

• 模型 ID 和定价在两大提供方处变动很快。列表工具描述的是当前版本知道的内容，可能与你的账号实际可见的模型有所偏差。

许可证

Apache 2.0。请参见 LICENSE。

由 Pink Pixel 用 💖 制作。