Image Gen

image-gen-mcp

使用你自己的 API 密钥，通过编码 Agent 生成和编辑图像。你可以要求生成博客封面、微调徽标或制作占位插图，文件会直接保存到项目中，Agent 可以读取并继续修改。

Google Gemini 图像模型（Nano Banana 系列）和 OpenAI GPT 图像模型通过同一个接口提供。你可以配置一个或两个服务提供商。

_{此横幅和仓库的社交预览卡片均由此服务使用 gemini-3.1-flash-image 以 16:9、2K 生成。提示词见 assets/README.md。}

安装

claude mcp add image-gen --scope user \
  --env GEMINI_API_KEY=your-gemini-key \
  --env OPENAI_API_KEY=your-openai-key \
  -- npx -y @nuver-labs/image-gen-mcp

启动一个新的 Claude Code 会话以加载配置，然后运行 claude mcp list 检查。

以下三点容易出错：

• 最后一个 --env 与服务名称之间至少要有一个选项。 上面的 --scope 就起到了这个作用。如果在一组 --env 后直接写服务名称，CLI 会将其当作另一个 KEY=value。
• 命令前必须加 --。 否则，服务自身的参数会被解析为 Claude Code 的参数。
• 不使用的服务提供商对应的 --env 行可以删除。至少需要配置一个。

从 Google AI Studio 和 OpenAI 平台获取密钥。

其他客户端

所有客户端使用同一个程序包。以下配置适用于 .mcp.json（项目范围，提交到仓库）和 Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "image-gen": {
      "command": "npx",
      "args": ["-y", "@nuver-labs/image-gen-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-key",
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

Claude Code 还支持为单个服务设置 "timeout": 600000，Claude Desktop 则不支持。Cursor 在 .cursor/mcp.json 中使用相同的配置格式。在 Windows 上，图形界面宿主有时无法找到 npx，因此请使用 "command": "cmd" 和 "args": ["/c", "npx", "-y", "@nuver-labs/image-gen-mcp"]。

使用方法

直接用自然语言提出要求：

• “生成一张 16:9 的黄昏灯塔主视觉图，并保存到 assets/hero.png”
• “把 public/logo.png 的背景设为透明”
• “生成 3 个方形扁平纸飞机图标变体，保存到 design/drafts/”

Agent 会调用 generate_image 或 edit_image，并在项目中指定绝对 output_path；文件会保存到磁盘。随后，Agent 可以读取保存路径，查看结果并进一步调整。如果调用失败，请让它运行 list_capabilities，查看实际配置了哪些内容。

工具

工具	功能
generate_image	根据文本提示词生成一个或多个图像文件，并返回保存路径的绝对路径。
edit_image	根据文本指令编辑或组合现有图像，不会覆盖源文件。
list_capabilities	查看已配置的服务提供商、默认模型和输出目录规则。

generate_image

参数	类型	说明
prompt	string, required	主题、风格、构图、颜色以及要渲染的任何文字
output_path	string	绝对文件路径（.png/.jpg/.webp）或目录。如果提供目录，文件名将根据提示词转换为 slug
provider	gemini | openai	覆盖默认提供方
model	string	Gemini：gemini-3.1-flash-image（默认）、gemini-3.1-flash-lite-image、gemini-3-pro-image、gemini-2.5-flash-image。OpenAI：gpt-image-2（默认）、gpt-image-1.5、gpt-image-1、gpt-image-1-mini
aspect_ratio	1:1 2:3 3:2 3:4 4:3 9:16 16:9 21:9	Gemini 和 gpt-image-2 支持精确比例。较早的 OpenAI 模型会近似采用以下分辨率：横向 1536x1024，纵向 1024x1536
n	1-4	Gemini 会依次生成，因此 n>1 时速度较慢
quality	low medium high auto	仅限 OpenAI。low 适用于低成本草稿
background	transparent opaque auto	仅限 OpenAI。适用于徽标和图标。需要 gpt-image-1.5 或更早版本，因此在 gpt-image-2 上设置 transparent 时会自动切换到 gpt-image-1.5，并在结果中说明
image_size	1K 2K 4K	仅限 Gemini 3.x
return_image	boolean	同时以内联方式返回第一张图片，使模型无需读取即可查看。会消耗上下文令牌

edit_image

包含以上所有参数，另有：

参数	类型	说明
source_paths	string[], required	1-16 个绝对路径（.png/.jpg/.jpeg/.webp）。第一个是编辑目标，其余为参考图。Gemini 使用 1-3 张效果最佳
input_fidelity	low | high	仅限 OpenAI。high 可保留人脸、徽标和细节。gpt-image-2 始终采用高保真，因此此参数对其无效

省略 output_path 时，结果将保存在第一张源图片所在目录。

list_capabilities

无参数。报告已配置的提供方是否可用（以布尔值表示，绝不显示密钥值）、默认提供方和模型、已知模型选项、输出目录回退顺序，以及当前生效的目录限制。

配置

变量	默认值	用途
GEMINI_API_KEY	(unset)	启用 Gemini 提供方
OPENAI_API_KEY	(unset)	启用 OpenAI 提供方
IMAGE_GEN_MCP_DEFAULT_PROVIDER	key-based	gemini 或 openai。未设置时：如果已设置 Gemini 密钥则使用 gemini，否则使用 openai
IMAGE_GEN_MCP_GEMINI_MODEL	gemini-3.1-flash-image	默认 Gemini 模型
IMAGE_GEN_MCP_OPENAI_MODEL	gpt-image-2	默认 OpenAI 模型
IMAGE_GEN_MCP_OUTPUT_DIR	(unset)	调用未传入 output_path 时的回退输出目录
IMAGE_GEN_MCP_ALLOWED_DIRS	(unset)	以逗号分隔的目录，所有读取和写入操作均限制在这些目录内。请参阅安全
IMAGE_GEN_MCP_TIMEOUT_MS	180000	对提供方 API 的单次请求超时时间
IMAGE_GEN_MCP_LOG_FILE	~/.image-gen-mcp/images.jsonl	JSONL 记录文件路径。使用绝对路径可更改位置，设为 none 可禁用文件记录

未指定 output_path 时，文件将保存到以下位置中第一个可用的位置：IMAGE_GEN_MCP_OUTPUT_DIR、 CLAUDE_PROJECT_DIR（由 Claude Code 设置，指向当前项目）、服务工作目录。

安全

此服务在本地运行，拥有你完整的用户权限，且不受 MCP 客户端沙箱保护。在允许其不受限制地使用工具之前，值得先了解这一点。

它能做什么。 将图像文件写入磁盘。读取你指定给 edit_image 的图像文件。将你的提示词以及任何 edit_image 源图像发送给你选择的服务商。发起会产生费用的 API 调用。这就是它的全部功能：三个工具，不执行 Shell 命令、不任意抓取 URL，也不收集遥测数据。

文件访问。 模型会选择 output_path 和 source_paths，默认情况下不受限制，因为这正是工具实用之处：你的 Agent 可以将文件保存到你正在处理的任意项目中。请注意，Claude Code 的工作目录边界并不适用于 MCP 服务，而且 Anthropic 不会对第三方 MCP 服务进行安全审计。

如需设置严格的边界，请配置 IMAGE_GEN_MCP_ALLOWED_DIRS：

IMAGE_GEN_MCP_ALLOWED_DIRS=/Users/you/projects,/Users/you/Desktop

之后，每个输出路径和每个 edit_image 源文件都必须解析到这些根目录之一内。路径会在经过 realpath 解析后进行比较，因此指向根目录之外的符号链接会被拒绝；路径包含关系按路径段而非字符串前缀判断，因此 /Users/you/projects-private 这样的同级目录无法蒙混过关。如果配置的目录均不存在，服务会拒绝所有文件访问，而不会悄悄地不受限制地运行。

API 密钥。 密钥只从环境中读取，传递给服务商 SDK 的构造函数，除此之外不会用于其他用途。密钥绝不会被记录日志、写入账本，也不会由 list_capabilities 返回，该工具只会报告布尔值。

风险在于你将密钥放在哪里，而不在于此服务如何使用它们。将密钥直接写入 ~/.claude.json 或 claude_desktop_config.json，会以明文形式存储，任何以你的身份运行的进程都能读取；而被要求读取自身配置的 Agent 可能会将密钥打印到对话记录中。建议通过 Shell 配置文件或密钥管理器导出密钥、对配置文件执行 chmod 600，并使用设有支出限额的专用密钥，而不是共用的生产密钥。

支出。 没有内置的速率限制或上限。处于重试循环中的 Agent 可能会在短时间内生成大量图像。请设置 OpenAI 硬性支出限额，并启用 Google Cloud 预算提醒。

本地日志。 ~/.image-gen-mcp/images.jsonl 中的账本包含每条提示词的明文截断副本，且会无限增长。使用 IMAGE_GEN_MCP_LOG_FILE=none 禁用它，并且不要将其提交到代码库。

提示词注入。 工具结果会重新进入模型的上下文。建议逐次调用审批，而不是始终允许此服务；审批时请查看输出路径以及任何 edit_image 源路径。请固定版本，并在升级前检查差异。

发现漏洞？请参阅 SECURITY.md。请勿提交公开问题。

日志记录

每次成功调用都会以两种方式记录一条结构化 JSON 条目：

• stderr，始终记录：一行 [image-gen-mcp] image {...}，可在 /mcp 输出和 Claude Code 日志中查看。
• JSONL 账本，默认启用：将相同的 JSON 追加到 ~/.image-gen-mcp/images.jsonl，每次调用占一行。账本写入失败不会中断生成，只会在 stderr 上警告一次。

每条记录包含服务商、模型、请求的尺寸、耗时秒数、截断后的提示词及其完整字符数、服务商报告的 Token 用量，以及每张图像的详细信息：保存路径、字节大小、易读的大小、MIME 类型和实际像素尺寸。

tail -n 20 ~/.image-gen-mcp/images.jsonl
jq 'select(.usage) | .usage.totalTokens' ~/.image-gen-mcp/images.jsonl

成本

每次调用都会产生 API 费用，通常每张图片需要几美分，具体费用因提供商、模型、质量和尺寸而异。适合草稿的低成本选项：OpenAI quality: low（在 gpt-image-2 上生成一张低质量的 1024x1024 图片约需 $0.006）或 gpt-image-1-mini，以及 Gemini gemini-3.1-flash-lite-image。未计费的密钥可能有 Gemini gemini-2.5-flash-image 免费层级，因此设置 IMAGE_GEN_MCP_GEMINI_MODEL=gemini-2.5-flash-image 即可将其设为默认模型。

超时

生成时间约为 10 到 120 秒，具体取决于模型和尺寸。Claude Code 的默认值较为宽裕，而且此服务会在长时间调用期间发送进度通知，因此通常无需调整。如果设置了较短的全局 MCP_TOOL_TIMEOUT，请在 .mcp.json 中为该服务添加 "timeout": 600000。

故障排查

• 服务日志会输出到 stderr，并带有 [image-gen-mcp] 前缀。Claude Code 会在 /mcp 输出和日志中显示这些日志。
• 已注册但没有工具：启动新会话，然后检查 claude mcp list 和 claude mcp get image-gen。
• Provider 'x' is not configured：MCP 服务环境中缺少该密钥。使用 --env 标志重新注册，或编辑配置。
• 输出位于允许的目录之外：已设置 IMAGE_GEN_MCP_ALLOWED_DIRS。运行 list_capabilities 查看根目录。
• 响应过大：return_image 会内联完整图片，可能超出 MCP 输出令牌限制（MAX_MCP_OUTPUT_TOKENS，默认值为 25k）。请将其关闭，让 Agent 读取已保存的文件。
• Gemini 拒绝请求：错误中包含结束原因和任何提供商文本。请改写提示词。

从源代码构建

需要 Node 22+ 和 pnpm。

git clone https://github.com/nuver-labs/image-gen-mcp.git
cd image-gen-mcp
pnpm install
pnpm build

然后将客户端指向 node /abs/path/to/image-gen-mcp/dist/index.js，而不是 npx -y @nuver-labs/image-gen-mcp。

pnpm test      # unit tests, no API keys needed
pnpm inspect   # list the tools over real MCP stdio

# Live tests. These cost real API credits.
GEMINI_API_KEY=... node dist/smoke.js --provider gemini
OPENAI_API_KEY=... node dist/smoke.js --provider openai
node dist/smoke.js --provider gemini --edit ./smoke-output/smoke-gen-gemini.png

贡献

欢迎提交错误报告、修复提供商特有问题以及改进文档。请参阅 CONTRIBUTING.md。对于规模更大的改动，请先提交 issue。

计划中的工作：支持 OpenAI 蒙版和图像修复，将 Gemini 旧版 generateContent 图像路径迁移到 Interactions API，并支持更多提供商。

许可证

MIT

---

由 Nuver Labs 构建。