Gemini 图像 MCP

一个 MCP 服务器，用于使用 Google 的 Gemini 图像模型（Nano Banana、Nano Banana 2、Nano Banana Pro）生成和编辑图像。它公开了一个工具 generate_image，像 Claude、Codex 和 Cline 这样的 AI 工具可以使用您自己的 API 密钥调用它。

它能做什么

• generate_image 处理文本到图像，以及当您传递参考图像（本地文件路径或 base64）时的编辑和合成。

• 每次调用都会公开每个生成参数：temperature (1)、topP (0.95)、topK、maxOutputTokens（flash/lite 为 65536，pro 为 32768）、seed、stopSequences、presencePenalty、frequencyPenalty、systemInstruction、thinkingLevel (minimal/high)、thinkingBudget、enableGoogleSearch（默认为 true）、imageSize (512/1K/2K/4K)、aspectRatio（默认 "auto" + 标准比例）、personGeneration。

• 附带一个 instructions 块和每个参数的描述，因此 MCP 客户端无需额外提示即可知道如何使用该工具。

• 将图像保存到磁盘并返回文件路径。响应中没有 base64，因此 4K 图像不会占用客户端的上下文窗口。

• 错误会附带提示信息（错误的密钥、速率限制、安全阻止、未知模型）返回，而不是原始的 API 转储。

• 使用 stdio 传输，这是本地 MCP 服务器的常规设置。

要求

• Bun 1.0+

• 来自 https://aistudio.google.com/apikey 的 Gemini API 密钥

安装

bun install

配置

三个环境变量，通常在 MCP 客户端的配置中设置：

您可以选择的模型：

模型也可以使用 models/ 前缀指定（例如 models/gemini-3.1-flash-image）。

客户端设置

Claude Desktop

将其添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "gemini-image": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/gemini-image-mcp/index.ts"],
      "env": {
        "GEMINI_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

Cline (VS Code)

cline_mcp_settings.json：

{
  "mcpServers": {
    "gemini-image": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/gemini-image-mcp/index.ts"],
      "env": {
        "GEMINI_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

Codex

~/.codex/config.toml：

[mcp_servers.gemini-image]
command = "bun"
args = ["run", "/absolute/path/to/gemini-image-mcp/index.ts"]
env = { GEMINI_API_KEY = "YOUR_KEY_HERE" }

从 npm (bunx/npx)

一旦包发布，将您的客户端指向 bunx 而不是：

{
  "mcpServers": {
    "gemini-image": {
      "command": "bunx",
      "args": ["gemini-image-mcp"],
      "env": { "GEMINI_API_KEY": "YOUR_KEY_HERE" }
    }
  }
}

generate_image 参数

只有 prompt 是必需的。其他所有参数都有适用于图像生成的合理默认值。

该工具返回一个文本摘要，其中包含保存的文件路径、模型、有效配置和令牌使用情况。它永远不会内联返回图像数据；打开文件查看结果。

您可以向 AI 询问的事情

• "生成一张 16:9 的雨夜东京街道英雄图，电影级霓虹灯光。"

• "编辑 /tmp/product.png：将其放在大理石桌上，带有柔和的晨光"（这使用了 referenceImages）。

• "使用 gemini-3-pro-image 生成一张带有确切标题 'LAUNCH DAY' 的 4K 海报。"

开发

bun test              # unit tests (config, schema, request/response parsing)
bun run typecheck     # tsc --noEmit
bun run inspector     # interactive MCP inspector (needs GEMINI_API_KEY)
bun run start         # run the server on stdio

故障排除

• "缺少 Gemini API 密钥"：将 GEMINI_API_KEY 放入客户端 MCP 配置的 env 块中。在 shell 中设置它对于 Claude Desktop 等 GUI 应用是不够的，因为它们不读取您的 shell 环境。

• 安全阻止：重新表述提示。如果涉及人物，请检查 personGeneration。

• 429 / 超出配额：等待并重试，或者坚持使用 gemini-3.1-flash-image，它的配额更高。

• 日志：服务器仅将日志写入 stderr。stdout 承载 MCP 协议，因此不要在任何地方添加 console.log。

作者

Thomi Jasir dev@venobi.com

许可证

MIT