Gemini Image Studio

gemini-image-studio-mcp

使用 Google Gemini 进行 AI 图像生成和编辑的 MCP 服务。创建网页素材、广告创意和品牌视觉内容，并通过结构化 JSON 编辑实现精准、可重复的控制。

有何不同

大多数 Gemini 图像 MCP 服务都只是基础的文本生成图像封装。这个服务增加了一个结构化编辑流程：

1. 生成：根据文本或 JSON 提示词生成图像
2. 分解：将图像拆解为结构化 JSON 蓝图（映射每个视觉组件）
3. 编辑：通过更改特定字段进行编辑 — subject[0].hair.color: "platinum_blonde" — 然后重新生成

这样就能进行精准、独立的修改，而不影响图像的其他部分。更改发色而不动背景。替换服装而不改变姿势。所有操作都通过点号表示法的 JSON 路径完成。

功能

• 5 个 MCP 工具 — 生成、分解、编辑、预设、列表
• 结构化 JSON 编辑 — 将图像分解为蓝图，并通过点号表示法编辑特定字段
• 自然语言编辑 — 或直接用英文描述要进行的更改
• 10 种内置预设 — Facebook 广告、Instagram 快拍、主视觉图、OG 图像、YouTube 缩略图等
• 参考图像支持 — 最多支持 14 张参考图像，以保持角色或物体的一致性
• 双模型支持 — Gemini 3.1 Flash（速度快）或 Gemini 3 Pro（质量最佳）
• 蓝图缓存 — 分解后的蓝图与图像一同缓存，可即时重新编辑
• Google Search 检索增强 — 通过网络搜索提升现实准确性
• 智能错误处理 — 遇到速率限制时重试、提供清晰的安全拦截提示、发出文件大小警告

快速开始

1. 获取 Gemini API 密钥

在 Google AI Studio 免费获取。

2. 安装

npm install -g gemini-image-studio-mcp

3. 添加到 Claude Code

claude mcp add gemini-image-studio-mcp -e GEMINI_API_KEY=your-key-here -- gemini-image-studio-mcp

或者将其添加到项目的 .claude/mcp.json：

{
  "mcpServers": {
    "gemini-image-studio-mcp": {
      "command": "npx",
      "args": ["-y", "gemini-image-studio-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

4. 使用

让 Claude 生成图像：

“为一家咖啡店创建一张光线温暖的 Facebook 广告图”

“为一家科技初创公司的落地页生成一张主视觉图”

“编辑主视觉图 — 将背景改成日落时的海滩”

工具

generate_image

根据文本或结构化 JSON 提示词创建新图像。

参数	类型	必填	描述
prompt	string	是	文本描述或 JSON 提示词
prompt_format	"text" | "json"	否	提示词格式（默认："text"）
preset	string	否	素材预设（例如，"facebook_ad"、"hero_image"）
aspect_ratio	string	否	覆盖宽高比（"1:1"、"16:9"、"9:16" 等）
image_size	"1K" | "2K" | "4K"	否	分辨率（默认："1K"）
model	"flash" | "pro"	否	Gemini 模型（默认："flash"）
reference_images	string[]	否	用于保持一致性的参考图像路径
output_name	string	否	自定义文件名
enable_search_grounding	boolean	否	使用 Google Search 提高准确性

decompose_image

将图像分析为结构化 JSON 蓝图 — 这是编辑工作流的第一步。

参数	类型	必填	描述
image_path	string	是	图像路径
detail_level	"basic" | "detailed" | "exhaustive"	否	细致程度（默认："detailed"）

返回完整蓝图，包含 subject、scene、technical、composition、text_rendering、style_modifiers 和 meta 部分；每个字段都精准描述图像的视觉组件。

edit_image

使用 JSON 更改或自然语言编辑图像。

参数	类型	必填	描述
image_path	string	是	图像路径
edit_type	"json" | "natural_language"	是	编辑模式
changes	object	用于 JSON 编辑	要更改的点表示法路径
instruction	string	用于自然语言编辑	自然语言指令
blueprint	object	否	蓝图（若省略，则从缓存自动加载）
model	"flash" | "pro"	否	模型（默认值："flash"）
output_name	string	否	自定义文件名

JSON 编辑示例 — 更改头发颜色并添加太阳镜：

{
  "image_path": "/output/portrait.png",
  "edit_type": "json",
  "changes": {
    "subject[0].hair.color": "platinum_blonde",
    "subject[0].accessories": [
      { "item": "sunglasses", "material": "metal", "color": "#C0C0C0" }
    ]
  }
}

自然语言编辑示例：

{
  "image_path": "/output/portrait.png",
  "edit_type": "natural_language",
  "instruction": "Change the background to a tropical beach at sunset. Keep the person exactly the same."
}

get_presets

列出可用的资源预设，包括尺寸、提示和规范。

参数	类型	必填	描述
category	"ad" | "web" | "social" | "all"	否	筛选条件（默认值："all"）

list_generated

浏览之前生成的图像。

参数	类型	必填	描述
filter	string	否	按文件名搜索
limit	number	否	结果数量上限（默认值：20）
include_blueprints	boolean	否	包含缓存的蓝图

JSON 编辑工作流

核心差异化优势——精确到字段级别的图像编辑：

Step 1: Generate
  generate_image(prompt: "Professional headshot, navy blazer", preset: "linkedin_post")
  → /output/headshot.png

Step 2: Decompose
  decompose_image(image_path: "/output/headshot.png")
  → JSON blueprint with every visual component mapped

Step 3: Edit (precise)
  edit_image(
    image_path: "/output/headshot.png",
    edit_type: "json",
    changes: {
      "subject[0].clothing[0].color": "#8B0000",
      "scene.lighting.type": "studio_softbox"
    }
  )
  → /output/headshot-edit-1.png (blazer changed to dark red, lighting adjusted)

Step 4: Edit (creative)
  edit_image(
    image_path: "/output/headshot-edit-1.png",
    edit_type: "natural_language",
    instruction: "Add warm bokeh to the background"
  )
  → /output/headshot-edit-1-edit-1.png

点表示法路径

subject[0].hair.color          → Hair color
subject[0].hair.style          → Hair style
subject[0].clothing[0].color   → First clothing item color
subject[0].accessories         → Add/change accessories
scene.lighting.type            → Lighting type
scene.location                 → Location/background
text_rendering.text_content    → Text in image
technical.lens                 → Camera lens
composition.framing            → Shot framing
style_modifiers.aesthetic      → Aesthetic style

内置预设

预设	类别	宽高比	尺寸	最适用于
facebook_ad	广告	1:1	1080x1080	Facebook/Instagram 信息流广告
instagram_story_ad	广告	9:16	1080x1920	Instagram/Facebook 快拍广告
google_display_banner	广告	16:9	1200x628	Google 展示广告网络
hero_image	Web	21:9	2560x1080	首屏主视觉区域
og_image	Web	16:9	1200x630	社交分享／链接预览
product_card	Web	4:5	800x1000	电商产品网格
email_header	Web	3:1	600x200	电子邮件营销页眉
linkedin_post	社交	1:1	1080x1080	LinkedIn 信息流帖子
twitter_post	社交	16:9	1200x675	Twitter/X 帖子
youtube_thumbnail	社交	16:9	1280x720	YouTube 缩略图

配置

变量	必填	默认值	描述
GEMINI_API_KEY	是	—	Google AI Studio API 密钥
OUTPUT_DIR	否	./output	生成图像的保存位置

集成

Claude Code

claude mcp add gemini-image-studio-mcp -e GEMINI_API_KEY=your-key -- gemini-image-studio-mcp

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "gemini-image-studio-mcp": {
      "command": "npx",
      "args": ["-y", "gemini-image-studio-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

任意 MCP 客户端

GEMINI_API_KEY=your-key npx gemini-image-studio-mcp

该服务通过 stdio 使用 Model Context Protocol 进行通信。

MCP 提示词与资源

此服务还提供：

• 提示词：nano_banana_expert — 调用它，让 Claude 全面了解 JSON 架构、编辑最佳实践和资源创建指南
• 资源：nanobanana://schema/prompt — 包含所有枚举值的原始 JSON 架构，可供程序化访问

模型

模型	ID	最适用于
Flash（默认）	gemini-3.1-flash-image-preview	快速生成、大批量任务、成本效益高
Pro	gemini-3-pro-image-preview	最高质量、复杂场景、专业资源

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/my-feature）
3. 运行测试（npm test）
4. 提交更改
5. 推送并创建 PR

许可证

MIT