gemini-image-mcp

一个基于 MCP (Model Context Protocol) 的 Node.js 服务：通过本地 OpenAI-compatible 网关（默认 http://127.0.0.1:8317）调用 Gemini 图片模型 gemini-3-pro-image-preview 生成图片，供 Claude Code/Claude Desktop 等 IDE 工具动态使用。

1) 安装

npm install

2) 环境变量（可选）

• OPENAI_BASE_URL：OpenAI-compatible 服务地址（默认 http://127.0.0.1:8317）
• OPENAI_API_KEY：如果你的网关需要鉴权就填（可留空）
• OPENAI_MODEL：默认 gemini-3-pro-image-preview
• OPENAI_IMAGE_SIZE：可选，仅作为未传入 size 时的默认值；建议让客户端在调用 generate_image 时自己传 size
• OPENAI_IMAGE_MODE：chat|images|auto，默认 chat（CLIProxyAPI 这类网关通常用 /v1/chat/completions 出图；若你的网关支持 /v1/images/generations 可设为 images）
• OPENAI_IMAGE_RETURN：path|image，默认 path（path 会把图片保存到本地并返回文件路径，避免 base64 导致 token 暴涨；image 返回 MCP image content）
• OPENAI_IMAGE_OUT_DIR：保存目录（默认 debug-output/；相对路径以项目根目录为基准）
• OPENAI_DEBUG：设为 1 时会在 stderr 打印上游请求信息（不打印 key）
• OPENAI_TIMEOUT_MS：默认 120000

可参考 .env.example。

3) 本地调试（不用放进 Claude Code）

推荐把 .env.example 复制成 .env，然后在 .env 里填好 OPENAI_API_KEY（.gitignore 已忽略 .env）。

• 直连上游调试（确认你的 http://127.0.0.1:8317 是否能出图）：
  • npm run debug:upstream -- --prompt "A beautiful sunset over mountains" --size 1024x1024
• 走 MCP 工具调试（等价于 Claude Code 调用 generate_image）：
  • npm run debug:mcp -- --prompt "A beautiful sunset over mountains" --n 1 --size 1024x1024

图片会输出到 debug-output/。

4) 作为 MCP Server 使用（stdio）

该项目是 stdio 传输方式的 MCP Server，不建议直接在终端手动运行（会等待客户端请求）。

在 Claude Code / Claude Desktop 的 MCP 配置里添加类似如下（按你的实际路径修改）：

{
  "mcpServers": {
    "gemini-image": {
      "command": "node",
      "args": ["d:/task/myself/nodejs/geminiimagemcp/src/index.js"],
      "env": {
        "OPENAI_BASE_URL": "http://127.0.0.1:8317",
        "OPENAI_API_KEY": "<YOUR_KEY>",
        "OPENAI_MODEL": "gemini-3-pro-image-preview"
      }
    }
  }
}

也可以直接参考 mcp.example.json。

5) 可用工具

• generate_image
  • 入参：prompt（必填）, size（可选）, n（可选，1-4）, output（可选：path|image）, outDir（可选）
  • 返回：默认返回保存后的图片文件路径（多行）；output=image 时返回 MCP image content（base64 + mimeType）