gemini-image

gemini-image-mcp

一个简单、专注的 MCP 服务，用于 Google Gemini 原生图像生成——“Nano Banana”模型。可通过 Claude Code、Claude Desktop 或任何基于 stdio 的 MCP 客户端生成、编辑和本地处理图像。仅提供两个工具，没有多余功能。

专为 Agent 打造：单次调用即可返回已保存的图像；或者通过一次调用移除背景，返回可直接使用的透明 PNG，而无需在 Agent 的上下文中传输图像数据。使用 Gemini 的 generateContent API（而非已弃用的 Imagen API）。

安装

npm install -g @jimothy-snicket/gemini-image-mcp

也可以直接使用 npx：

npx -y @jimothy-snicket/gemini-image-mcp

Claude Code（单条命令）：

claude mcp add gemini-image -- npx -y @jimothy-snicket/gemini-image-mcp

需要设置 GEMINI_API_KEY 环境变量——详情请参阅设置。

设置配置文件（可选）：

npx @jimothy-snicket/gemini-image-mcp --init

此命令会创建包含注释默认值的 ~/.gemini-image-mcp.json。如需项目专属的覆盖配置：

npx @jimothy-snicket/gemini-image-mcp --init --local

功能

generate_image — AI 驱动

• 文本生成图像——描述你的需求，即可生成图像
• 图像编辑——提供参考图像和编辑说明
• 视频生成图像——模型会观看视频，并根据理解合成新图像：YouTube 缩略图、视频片段海报、摘要信息图、风格迁移静帧。请参阅高级功能
• 思考深度控制——对于依赖推理的渲染（信息图、图表、密集排版），可设置 thinkingLevel: "HIGH"；其他情况默认使用成本较低的 MINIMAL
• 单次调用生成透明素材——removeBackground 默认返回干净的透明 PNG：使用本地 AI 抠图（适用于任何主体；可选附加组件，见下文），也可使用内置的绿幕／白色阈值抠图。无需额外 API 费用
• 多轮编辑——传入 sessionId，即可在多次调用中优化图像，并将之前的轮次保留为上下文
• 多图输入——为编辑和角色／风格一致性提供参考图像（各模型限制不同；由 API 强制执行）
• 费用报告——每个响应都包含 Token 数量、预估美元费用和会话总计
• 速率限制——可配置每小时的请求数和费用上限，防止 Agent 失控
• 自动发现模型——启动时根据你的 API 密钥检测可用的图像模型
• 种子——通过整数种子实现可复现的生成
• 搜索依据——利用实时 Google Search 结果为渲染提供依据；"web+image" 还会获取图片搜索结果，用于情绪板和趋势参考，并返回来源以便标注。请参阅高级功能

process_image — 本地处理（免费，无 API 调用）

• 裁剪——像素精确、按宽高比（居中）或按焦点（注意力／熵）
• 调整尺寸——调整宽度、高度或两者（保持宽高比）
• 移除背景——基于阈值（白色背景）或色度键（绿幕、任意纯色）
• 色度键处理流程——使用平滑阶跃羽化、溢色抑制和边缘抗锯齿的 HSV 抠图
• 修剪——自动移除空白边框
• 格式转换——支持 PNG、JPEG、WebP，并可控制质量

两种工具

• 输出整理——使用有意义的文件名并自动递增版本，支持子文件夹
• 生成清单——generations.jsonl 会记录每次生成的提示词、参数和费用
• 完整宽高比支持——1:1、16:9、9:16、3:2、2:3、4:3、3:4、21:9
• 分辨率控制——1K、2K、4K

设置

1. 获取 Gemini API 密钥

前往 Google AI Studio 并创建 API 密钥。

需要启用计费：图像生成没有免费层级——免费层级的密钥调用任何图像模型时都会收到 429 RESOURCE_EXHAUSTED（配额上限为 0）。请在该密钥所属的 Google Cloud 项目中启用按需付费计费（使用情况和计费）。根据模型和分辨率不同，每张图像费用约为 $0.03–$0.24；最便宜的模型（默认模型 gemini-3.1-flash-lite-image）每张图像约 $0.034。

2. 设置 API 密钥

服务会从 GEMINI_API_KEY 环境变量读取密钥。设置一次，即可在每个会话中使用：

Windows（PowerShell — 以管理员身份运行）：

[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key-here', 'User')

然后重启终端。

macOS / Linux：

echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

（如果你使用 zsh，请使用 ~/.zshrc。）

验证是否已设置：

echo $GEMINI_API_KEY

3. 连接到 MCP 客户端

选择符合你使用 MCP 方式的方法：

Claude Code（单行命令）

claude mcp add gemini-image -- npx -y @jimothy-snicket/gemini-image-mcp

Claude Code 会自动从你的环境中读取 GEMINI_API_KEY。

Claude Code（手动配置 .mcp.json）

将以下内容添加到项目根目录中的 .mcp.json，或添加到 ~/.claude/.mcp.json 以供全局使用：

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "@jimothy-snicket/gemini-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
      }
    }
  }
}

${GEMINI_API_KEY} 语法会从 shell 环境中读取值，因此你的实际密钥不会写入配置文件。

Claude Desktop

编辑 claude_desktop_config.json：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "@jimothy-snicket/gemini-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
      }
    }
  }
}

保存后重启 Claude Desktop。

其他 MCP 客户端

任何支持 stdio 传输的客户端都可以使用。将其指向 npx -y @jimothy-snicket/gemini-image-mcp，并在环境中传入 GEMINI_API_KEY。

安全说明

• 切勿将 API 密钥提交到版本控制中。配置文件中的 ${GEMINI_API_KEY} 语法引用的是你的环境变量，密钥本身仍保存在 shell 配置文件中。
• 如果项目仓库中包含 .mcp.json，请将其添加到 .gitignore，或改用全局配置 ~/.claude/.mcp.json。
• 如需提高安全性，可以使用包装脚本从操作系统的密钥链（macOS Keychain、Windows Credential Manager）读取密钥，并在注入密钥后启动服务。

配置

以下配置均为可选项。唯一必需的设置是 GEMINI_API_KEY（见上文）。

变量	默认值	描述
OUTPUT_DIR	~/gemini-images	保存图像的默认目录
DEFAULT_MODEL	gemini-3.1-flash-lite-image	默认 Gemini 模型
LOG_LEVEL	info	debug、info 或 error
REQUEST_TIMEOUT_MS	60000	API 请求超时时间，单位为毫秒
MAX_REQUESTS_PER_HOUR	0（无限制）	每个滚动小时内最多生成的图像数
MAX_COST_PER_HOUR	0（无限制）	每个滚动小时内的最高预估费用（USD）
SESSION_TIMEOUT_MS	1800000（30 分钟）	多轮会话过期时间
GEMINI_IMAGE_AUTO_INSTALL	1（开启）	首次使用 removeBackground: { mode: "auto" } 时自动安装 AI 抠图引擎。设为 0 可禁用（此时 auto 会回退到色度/阈值模式，并提供说明）

按照设置 GEMINI_API_KEY 的相同方式设置这些变量，或将它们传入 MCP 配置中的 env 块。

建议启用速率限制，尤其是在 Agent 可以使用此工具时。循环运行的 Agent 可能会快速生成图像，因此建议将 MAX_REQUESTS_PER_HOUR=20 和 MAX_COST_PER_HOUR=5 设为合理的默认值。

配置文件

也可以使用 JSON 配置文件代替环境变量。运行以下命令创建配置文件：

npx @jimothy-snicket/gemini-image-mcp --init

此命令会创建 ~/.gemini-image-mcp.json，其中包含所有默认值和行内说明。编辑该文件即可设置你的偏好。

优先级： 环境变量 > 本地配置（CWD 中的 .gemini-image-mcp.json）> 全局配置（~/.gemini-image-mcp.json）> 默认值。

你还可以设置每个工具的默认值，让每次请求都使用你偏好的设置：

{
  "defaultModel": "gemini-3.1-flash-image",
  "defaults": {
    "generate": {
      "aspectRatio": "16:9",
      "resolution": "2K"
    },
    "process": {
      "removeBackground": { "color": "#00FF00" },
      "trim": true
    }
  }
}

每次请求的参数始终优先于配置默认值。

自定义定价。 费用估算使用内置的每 Token 费率表（没有可用于获取实时定价的 API）。如果你使用的模型尚未收录在费率表中，或者 Google 在此软件包更新前调整了费率，可以添加 pricingOverrides，以确保费用报告准确，无需等待版本发布：

{
  "pricingOverrides": {
    "some-new-image-model": {
      "inputPerMillion": 0.5,
      "textOutputPerMillion": 60,
      "imageOutputPerMillion": 60,
      "thinkingPerMillion": 60
    }
  }
}

无论是内置费率表还是覆盖项中未收录的模型仍可生成图像，其费用会报告为 unknown，而不会进行猜测。

工具：generate_image

参数

参数	必填	描述
prompt	是	文本描述或编辑指令
images	否	输入图像/参考图像的文件路径数组
model	否	Gemini 模型 ID
aspectRatio	否	1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9，以及 1:4、4:1、1:8、8:1（gemini-3.1-flash-image）。由 API 验证。
resolution	否	512（仅限 gemini-3.1-flash-image）、1K、2K、4K
outputDir	否	覆盖此请求的输出目录
filename	否	保存文件的基本名称（例如 hero-banner）。若有重复则自动添加版本号。
subfolder	否	输出目录中的子文件夹（例如 landing-page）
sessionId	否	从之前的响应继续多轮编辑会话
seed	否	用于可复现生成的整数种子
grounding	否	"web" = Google 搜索 grounding；"web+image" 会加入图片搜索结果（仅限 gemini-3.1-flash-image）。参见高级功能
useSearchGrounding	否	grounding: "web" 的旧版别名
thinkingLevel	否	"MINIMAL"（默认）或 "HIGH" — gemini-3.1-flash 系列的思考深度。参见高级功能
videos	否	用于视频转图像的输入视频文件路径数组（gemini-3.1-flash 系列）。参见高级功能
removeBackground	否	返回透明 PNG 抠图。{ "mode": "auto" } = 本地 AI 蒙版（适用于任何主体；默认）；{ "mode": "chroma" } = 绿幕；{ "mode": "threshold" } = 去除白色（线稿）。不产生额外 API 费用

示例响应

{
  "imagePath": "/home/user/gemini-images/hero-banner.png",
  "mimeType": "image/png",
  "model": "gemini-3.1-flash-lite-image",
  "sessionId": "session-1711929600000-a1b2c3",
  "sessionTurn": 1,
  "usage": {
    "promptTokens": 5,
    "outputTokens": 1295,
    "imageTokens": 1290,
    "thinkingTokens": 412,
    "totalTokens": 1712,
    "estimatedCost": "$0.0390",
    "pricingVerifiedDate": "2026-09-16"
  },
  "session": {
    "generationsThisSession": 3,
    "totalCostThisSession": "$0.1161",
    "generationsThisHour": 5,
    "limit": {
      "maxPerHour": 20,
      "maxCostPerHour": 5,
      "remainingThisHour": 15
    }
  }
}

用法示例

文本生成图像：

“生成一张 SaaS 着陆页主视觉图，采用现代渐变风格，16:9”

图像编辑：

“使用深色主题重新设计这张截图的页眉”（附带图像路径）

迭代编辑（多轮）：

生成图像后，再次调用并传入返回的 sessionId，以及“让它更简约”之类的改进要求 — 先前的图像会保留在上下文中。

整理输出：

使用 filename: "hero"、subfolder: "landing-page" 生成“主视觉横幅” → 保存到 ~/gemini-images/landing-page/hero.png

高质量：

“大理石上的耳机写实产品照，4K”（使用 gemini-3-pro-image）

透明素材（一次调用）：

使用 removeBackground: { "mode": "auto" } 生成“一只亮面红色运动鞋的产品照” → 得到可直接使用的透明 PNG。本地 AI 蒙版适用于任何主体 — 无需绿幕。

工具：process_image

通过 sharp 在本地处理图像。免费、快速，无需调用 API。

参数

参数	必填	描述
imagePath	是	要处理的图像文件路径
crop	否	按像素尺寸、宽高比或焦点策略裁剪
resize	否	调整为指定宽度/高度（保持宽高比）
removeBackground	否	移除背景：{ "mode": "auto" }（AI 蒙版，适用于任何主体）、{ "mode": "chroma" }（绿幕）或 { "mode": "threshold" }（白色）。若设置了 color，默认使用 chroma；否则默认使用 threshold
trim	否	自动移除空白/透明边框
format	否	转换为 png、jpeg 或 webp
quality	否	JPEG/WebP 的输出质量（1-100）
filename	否	保存文件的基本名称。若有重复则自动添加版本号。
subfolder	否	输出目录中的子文件夹
outputDir	否	覆盖输出目录

裁剪选项

// Pixel-exact
{"width": 500, "height": 300, "left": 100, "top": 50}

// Aspect ratio (center crop)
{"aspectRatio": "16:9"}

// Focal point — shifts crop to the most interesting region
{"aspectRatio": "16:9", "strategy": "attention"}

// Detail-based — shifts crop to the most detailed region
{"aspectRatio": "16:9", "strategy": "entropy"}

背景移除选项

// AI semantic matte — best quality, works on ANY subject
{"mode": "auto"}

// White/light background (threshold)
{"mode": "threshold", "threshold": 240}

// Green screen (chroma key)
{"mode": "chroma", "color": "#00FF00"}

// Any solid colour
{"mode": "chroma", "color": "#0000FF", "tolerance": 60}

mode: "auto" 会运行本地 BiRefNet 蒙版，根据语义分离主体，因此可以处理头发、玻璃以及绿色／黄色主体，而色度键控无法做到。蒙版引擎不会随软件包一起捆绑（使基础安装包保持在约 65 MB）。首次调用 auto 时，服务会自动安装它（@huggingface/transformers，约 340 MB）以及 fp16 模型（约 109 MB）——首次会暂停一两分钟，之后便会在本地运行，不会产生额外 API 费用。设置 GEMINI_IMAGE_AUTO_INSTALL=0 可禁用自动安装（此时 auto 会改为返回图像，并提示手动安装）。chroma 和 threshold 无需额外安装。

色度键控（mode: "chroma"）使用 HSV 键控、smoothstep 羽化、溢色抑制和 5 遍边缘抗锯齿（默认容差为 80）。对于 AI 生成的绿幕，请使用 #00FF00——相比匹配 Gemini 生成的确切色调，效果更好。

**注意：**色度键控会破坏与键色相同的主体（绿色／黄色），以及透明／反光主体（玻璃）——绿色鹦鹉会消失。对于这些情况，请使用 mode: "auto"（AI 蒙版会保留它们），或采用画布方案：向 generate_image 提供纯色背景图像，让 Gemini 在正确的光照下放置主体。对于玻璃等真正透明的物体，画布方案仍然是最佳选择，因为这类物体应该透出最终背景，而不是被抠出来。

常见工作流

将主体放在特定背景上（画布方案）：

generate_image → "Place a [subject] on this background" with images: [solid colour canvas]

一次 API 调用。最适合黄色、绿色或玻璃主体，因为色度键控难以处理它们。

透明素材（一次调用）：

generate_image → "A product photo of <subject>" with removeBackground: {mode: "auto"}

一次 API 调用 → 透明 PNG。本地 AI 蒙版适用于任何主体。（对于玻璃等真正透明／反光的物体，上面的画布方案仍然是最佳选择。）

从绿幕生成透明素材（零依赖）：

generate_image → "A product photo on a bright green background"
process_image → removeBackground {mode: "chroma"} + trim

完全无需蒙版模型——最适合在受限／离线机器上处理高对比度主体。

从生成的徽标制作网站图标：

process_image → removeBackground {threshold: 230} + trim + resize {width: 192, height: 192}

从照片制作社交媒体卡片：

process_image → crop {aspectRatio: "16:9", strategy: "attention"} + resize {width: 1200}

转换为适用于网页的 WebP：

process_image → format: "webp" + quality: 85

高级功能

这些是 generate_image 中可选启用的参数。大多数请求无需使用它们——为了精简 Agent 上下文，这里对它们进行说明，而非写入工具架构。

视频转图像（videos）

模型会观看你的视频，并根据它理解的内容（主题、氛围、色彩和动作）合成一张新图像，而不是复制某一帧。如果你只想提取一帧，请使用 ffmpeg；此功能适用于需要理解视频内容的图像：

• YouTube 缩略图——“观看我的视频并制作一张吸引点击的缩略图”（主要用途：无需反复拖动进度条寻找清晰的画面）
• 海报和封面图——游戏实况片段 → 主视觉图，演出录像 → 演出海报，产品演示 → 精美产品图
• 摘要信息图——“用图表展示这段教程视频中的关键步骤”
• 风格迁移静帧——将舞蹈视频制成铅笔素描，将家庭录像制成漫画分镜

{
  "prompt": "A bold movie poster for this video, dramatic typography",
  "videos": ["./clip.mp4"],
  "model": "gemini-3.1-flash-image"
}

• 支持 gemini-3.1-flash 系列（gemini-3.1-flash-image、gemini-3.1-flash-lite-image）；其他模型不支持。
• 接受本地文件（mp4、mov、webm、avi、mpeg、wmv、flv、3gpp），每个文件最大 500MB，每次调用最多 3 个。每段视频都会上传到 Google 的 Files API，轮询直至处理完成，用于本次调用后删除。视频令牌计入输入（2 秒片段约为 140 个令牌）。
• 不能与 sessionId 结合使用——会话仅支持文本和图像，视频轮次不会创建会话（上传文件会在调用后删除，因此存储的会话重放时会引用已失效的文件）。
• 上传和服务端处理在生成调用之前进行，每段视频的处理时限为 120 秒，不受 REQUEST_TIMEOUT_MS 限制（该设置仅限制生成调用本身）。
• 你必须拥有所上传视频的必要权利。
• 范围说明：此功能用于视频输入。视频生成属于另一种模型系列（Google 的 Veo，通过其专属 API 调用），不在此服务的范围内。

思考深度（thinkingLevel）

所有 Gemini 3 图像模型都会在渲染前进行“思考”。默认值 MINIMAL 可降低成本和延迟。对于质量取决于推理的渲染，请使用 "HIGH"：例如信息图、图表、菜单、密集排版和多步骤构图。

{ "prompt": "An infographic explaining the water cycle with labeled diagrams", "thinkingLevel": "HIGH" }

支持 gemini-3.1-flash 系列（API 会在其他地方进行验证）。可在配置文件中通过 defaults.generate.thinkingLevel 设置为项目默认值。

图像搜索 grounding（grounding: "web+image"）

grounding: "web" 会根据 Google 搜索的实时结果（天气、股票图表、时事）为渲染提供依据。"web+image" 仅适用于 gemini-3.1-flash-image，还会引入图像搜索结果，适用于情绪板和趋势参考。

使用 grounding 时，响应会包含一个 grounding 对象：来源 chunks（URI 和标题，最多 5 项）、searchQueries 和 searchEntryPointHtml。Google 的服务条款要求：展示基于 grounding 的结果时，必须显示搜索建议入口——请将 searchEntryPointHtml 原样传递给用户（这是 Google 专门为此用途提供的可直接渲染的 HTML）。

gemini-3.1-flash-lite-image 不支持此功能（API 会拒绝该模型上的 grounding）。

模型

模型	优势	分辨率	备注
gemini-3.1-flash-lite-image	成本最低（约 $0.034/张图像），支持视频输入	1K	默认（Nano Banana 2 Lite）。不支持搜索 grounding；最多支持 14 张参考图像，但未针对多图或多轮编辑进行优化——此类场景优先使用 3.1-flash
gemini-3.1-flash-image	速度与质量兼备，支持搜索 grounding（网页 + 图像）和视频输入	512、1K、2K、4K	每张 1K 图像约 $0.07。最多支持 10 张对象参考图像 + 4 张角色参考图像 + 3 张风格参考图像
gemini-3-pro-image	质量最佳，支持文本渲染	1K、2K、4K	每张 1K 图像约 $0.13。最多支持 6 张对象参考图像 + 5 张角色参考图像
gemini-2.5-flash-image	旧版	1K	将于 2026-10-02 停止服务

已停用的 -preview ID（gemini-3-pro-image-preview、gemini-3.1-flash-image-preview）可能仍会出现在你的密钥模型列表中，但它们已于 2026-06-25 停用——请使用上方的 GA ID。服务会在启动时发现你的 API 密钥支持的图像模型，并根据实时列表验证每个请求，因此无需更新即可使用新模型。

开发

bun install
bun run build     # TypeScript -> dist/
bun run dev       # Run directly with Bun

许可证

MIT