Ultimate Gemini MCP

Ultimate Gemini MCP

面向 Google Gemini 3.1 Flash Image 的 MCP 服务——快速生成图像，具备高级推理能力，支持 512px–4K 分辨率、最多 14 张参考图像、Google 搜索 grounding 和自动思考模式。

---

设置

Claude Desktop

在 MCP 配置文件（mcp.json / .claude.json）中添加：

{
  "mcpServers": {
    "ultimate-gemini": {
      "command": "uvx",
      "args": ["ultimate-gemini-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

所有生成的图像都包含不可见的 SynthID 水印，用于验证真实性和追踪来源。

---

功能

Gemini 3.1 Flash Image

• 高分辨率输出：512px、1K、2K 和 4K 分辨率
• 高级文本渲染：在信息图表、菜单、图表和徽标中呈现清晰易读、风格化的文本
• 最多 14 张参考图像：最多 10 个物体 + 4 个角色，确保风格和角色一致性
• Google 搜索 grounding：实时数据（天气、股票、活动、地图）
• Google 图片搜索：从网页图片获取视觉上下文——模型可以找到任何事物的真实图像
• 思考模式：可配置推理——“minimal”（快速）或“high”（最高质量）
• 透明背景：切换一个标记，即可生成可直接使用的透明 PNG/WebP 抠图，并带有真正的 alpha 通道；通过两遍差分蒙版恢复（先在白色背景上生成，再编辑为黑色，然后求解 alpha）。呈现真实的柔和边缘、辉光和玻璃质感，不会出现颜色光晕。仅需 Pillow——无需额外依赖。需要额外调用一次模型（成本约为 2 倍）。
• 专用应用图标 / 徽标工具：generate_app_icon 每次都会强制生成正方形、透明背景、1024px 的 PNG——无法生成非正方形或不透明背景的图标

这个模型与众不同。 传统图像生成器完全依赖训练数据，而 Gemini 3.1 Flash 可以实时访问 Google 搜索和图片搜索。它能找到产品、人物、活动或任何在线存在事物的真实参考。“Way of Wade 12” → 生成真实的球鞋。“Tony Hawk” → 找到真实照片。不要过度提示——让模型自由发挥。

服务功能

• 批量处理：并行生成多张图像（最多同时处理 8 张）
• 26 个专家提示词模板：适用于摄影、电影、故事板等的 MCP 斜杠命令
• 灵活的宽高比：14 种选项——1:1、1:4、1:8、2:3、3:2、3:4、4:1、4:3、4:5、5:4、8:1、9:16、16:9、21:9
• 通过环境变量配置：输出目录、默认尺寸、超时等

---

展示

照片级真实感能力

Jensen Huang — GPU 冲浪

Elon Musk — 火星国际象棋对决

Jensen Huang — GPU 厨房

Elon Musk — Cybertruck 交响乐

Jensen Huang — 水下数据中心

Elon Musk — SpaceX 滑板

Google 搜索 grounding

旧金山当前天气

Google 图片搜索

花上的蝴蝶

不同分辨率

512px（最快）

1K

2K

---

快速开始

前提条件

• Python 3.11+
• Google Gemini API 密钥（提供免费套餐）

安装

使用 uvx（推荐 — 无需安装）：

uvx ultimate-gemini-mcp@latest

注意： 使用 @latest 确保 uv 始终从 PyPI 获取最新版本。否则，uv 可能会使用缓存环境。

使用 pip：

pip install ultimate-gemini-mcp

从源码安装：

git clone https://github.com/anand-92/ultimate-image-gen-mcp
cd ultimate-image-gen-mcp
uv sync

配置文件位置：

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

macOS spawn uvx ENOENT 错误：使用完整路径 — 通过 which uvx 查找，然后设置 "command": "/Users/you/.local/bin/uvx"。

Claude Code

claude mcp add ultimate-gemini \
  --env GEMINI_API_KEY=your-api-key \
  -- uvx ultimate-gemini-mcp@latest

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "ultimate-gemini": {
      "command": "uvx",
      "args": ["ultimate-gemini-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

图像默认保存到 ~/gemini_images。添加 "OUTPUT_DIR": "/your/path" 可自定义保存位置。

---

工具

generate_image

使用 Gemini 3.1 Flash Image 生成图像。

参数	类型	默认值	描述
prompt	string	必填	文本描述。越简洁越好 — “Tony Hawk kickflip”胜过冗长的描述。启用搜索后，模型可以自动查找参考资料。
aspect_ratio	string	1:1	可选值：1:1 1:4 1:8 2:3 3:2 3:4 4:1 4:3 4:5 5:4 8:1 9:16 16:9 21:9
image_size	string	2K	512px、1K、2K 或 4K
output_format	string	png	png、jpeg 或 webp
reference_image_paths	list	[]	最多 14 个本地图片路径（10 个物体 + 4 个角色）
enable_google_search	bool	false	对于产品、人物、事件 — 任何当前存在的事物，请启用此项。模型会搜索 Google 获取真实信息。
enable_image_search	bool	false	对于视觉参考，请启用此项。模型会查找实际图像作为参考。这非常实用 — 它可以参考任何人或事物的真实照片。
thinking_level	string	minimal	minimal（快速）或 high（最佳质量）
response_modalities	list	["TEXT","IMAGE"]	["TEXT","IMAGE"]、["IMAGE"] 或 ["TEXT"]
transparent_background	bool	false	通过两阶段差分遮罩生成透明背景的 PNG/WebP 抠图（成本约为 2 倍；见下文）
preserve_original	bool	true	同时保留第一阶段（白色背景）图像，而不只是抠图
alpha_output_format	string	png	支持 Alpha 通道的输出格式：png 或 webp

图像尺寸指南：

• 512px — 速度最快、成本最低（0.5K）
• 1K — 速度快，适合测试（约 1-2 MB）
• 2K — 推荐用于大多数场景（约 3-5 MB）
• 4K — 生产素材的最高画质（约 8-15 MB）

透明背景——设置一个标志，获得真正的 Alpha 抠图

只需设置 transparent_background=true。 返回的透明 PNG/WebP（带真正的 Alpha 通道）可直接使用，路径为 transparent_path——无需手动抠图、无需调用第二个工具，也无需后续步骤。

要生成应用图标或徽标？请改用专用的 generate_app_icon 工具——它会强制设置正方形、透明背景和 1024px PNG，避免图标约束设置错误。

此功能在底层使用双遍差分蒙版。首先在纯白（#FFFFFF）背景上渲染主体，然后将图像编辑为纯黑（#000000）背景，再将两帧合并，逐像素求解 Alpha 值：由于每个通道上 obs_white − obs_black = (1−α)·255，因此 α = 1 − mean(obs_white − obs_black)/255，并从黑底帧中去除前景色的预乘。由于不使用颜色键，因此不会出现绿色溢色或光晕；Alpha 值是小数，因此柔和边缘、辉光、玻璃效果和淡淡的阴影都能保留。仅依赖 Pillow，无需下载机器学习模型——但要额外调用一次模型（约 2 倍的 token 用量和延迟）。

此技术假设编辑步骤只更改了背景。如果模型在两次处理之间改变了主体，蒙版效果就会下降——仍会返回结果（通过 aligned/alignment_error 标志提示，并在 post_processing_warnings 中添加醒目警告），由你决定是否重新生成。

每张返回的图像都会新增：transparent_path、background_removed、background_removal_mode（"difference_matte"）、aligned、alignment_error、alpha_output_format 和 post_processing_warnings。默认情况下，处理第 1 遍（白底）的原图会与抠图结果一并保留（preserve_original=true）。

// generate_image(prompt="a friendly robot mascot", transparent_background=true)
{
  "images": [{
    "path": "/path/to/a-friendly-robot-mascot-...png",            // pass-1 (white bg)
    "transparent_path": "/path/to/a-friendly-robot-mascot-...-transparent.png",
    "background_removed": true,
    "background_removal_mode": "difference_matte",
    "aligned": true,
    "alignment_error": 0.004,
    "alpha_output_format": "png",
    "post_processing_warnings": []
  }]
}

此功能适用于边缘清晰的主体以及柔和的辉光/玻璃效果。唯一的失效情况是编辑步骤改变了主体（通过 aligned: false 标记）——如果边缘看起来有重影，请重新生成。

---

generate_app_icon

专为应用图标和徽标设计。正方形、透明背景和 1024px 都是强制设置——没有 aspect_ratio、image_size、output_format 或 transparent_background 选项可供误设。每个结果都是带真正 Alpha 通道的 PNG，路径为 transparent_path，可直接放入 .iconset 目录，再用 iconutil -c icns 转换。

参数	类型	默认值	说明
prompt	string	必填	仅描述图标/徽标图案——构图和透明度由工具处理
reference_image_paths	str | list	null	品牌/风格参考图像路径，最多 14 个
enable_google_search	bool	false	根据真实网页参考资料生成设计
enable_image_search	bool	false	使用 Google Image Search 获取视觉上下文
thinking_level	string	high	minimal 或 high（图标生成使用 high 效果更好）
allow_icon_words_in_prompt	bool	false	特殊开关——仅当类似“logo”的词确实是主体的一部分时，才绕过提示词检查

prompt 必须且只能描述主体，不能描述交付物。 此工具会将你描述的内容直接生成为图标，因此提示词中的“app icon”“logo”“favicon”或“squircle”等构图词会被拒绝（只有当此类词语确实是所描绘主体的一部分时，才设置 allow_icon_words_in_prompt=true）。正确示例："a glowing electric-blue magnifying glass over a network graph"。错误示例："an app icon of a magnifying glass"。

// generate_app_icon(prompt="a glowing electric-blue magnifying glass over a network graph")
{
  "images": [{
    "transparent_path": "/path/to/...-transparent.png",  // square, 1024px, alpha
    "background_removed": true,
    "alpha_output_format": "png"
  }]
}

---

batch_generate

并行生成多张图像。

参数	类型	默认值	描述
prompts	list	必填	提示词字符串列表（最多 8 个）
aspect_ratio	string	1:1	应用于所有图像的宽高比
image_size	string	2K	所有图像的分辨率
output_format	string	png	所有图像的格式
response_modalities	list	["TEXT","IMAGE"]	所有图像的响应模态
batch_size	int	8	并发请求数上限
enable_image_search	bool	false	使用 Google Image Search 获取视觉上下文
thinking_level	string	minimal	minimal 或 high
transparent_background	bool	false	对每张图像应用两遍差异蒙版（每张图像都会额外调用一次模型）
preserve_original	bool	true	同时保留第 1 遍生成的（白色背景）图像
alpha_output_format	string	png	透明背景输出格式：png 或 webp

---

MCP 提示词模板

Claude Code 中提供 26 个专家提示词模板，可通过 MCP 斜杠命令使用（输入 / 浏览）。每个模板都会返回精心编写的提示词和推荐参数，可直接传给 generate_image 或 batch_generate。对于应用图标和徽标，请改用专用工具 generate_app_icon。

命令	描述	默认宽高比
photography_shot	包含镜头和灯光规格的照片级真实感镜头	16:9
cinematic_scene	使用电影摄影术语描述的电影剧照	21:9
product_mockup	商业电商摄影	1:1 或 4:5
batch_storyboard	多场景故事板 → 调用 batch_generate	16:9
macro_shot	使用微型聚光灯照明的极致微距镜头	1:1
fashion_portrait	带有挡光板阴影图案的时尚编辑风格人像	4:5
technical_cutaway	Stephen Biesty 风格剖面图	3:2、4K，仅 IMAGE
flat_lay	俯拍 Knolling 摄影	1:1
action_freeze	高速频闪灯拍摄，背景带有运动模糊	16:9
night_street	氛围感夜间街景，采用实景光源	16:9
drone_aerial	黄金时段垂直俯拍航拍	4:5、4K，仅 IMAGE
stylized_3d_render	UE5 风格渲染，带有次表面散射	1:1，仅 IMAGE
sem_microscopy	扫描电子显微镜伪彩色图像	1:1，仅 IMAGE
double_exposure	剪影融合的双重曝光	2:3，仅 IMAGE
architectural_viz	光线追踪建筑可视化	3:2、4K
isometric_illustration	正交等距 3D 插画	1:1，仅 IMAGE
food_photography	高端逆光美食摄影	4:5
motion_blur	后帘同步慢速快门序列	16:9
typography_physical	嵌入实体环境中的文字	16:9、4K，仅 IMAGE
retro_futurism	20 世纪 70 年代磁带未来主义模拟科幻风格	4:3，仅 IMAGE
surreal_dreamscape	展现不可能物理现象的超现实主义场景	1:1，仅 IMAGE
character_sheet	电子游戏角色概念设计图	3:2、4K，仅 IMAGE
pbr_texture	带有掠射光的无缝 PBR 纹理贴图	1:1，仅 IMAGE
historical_photo	符合时代特征并模拟胶片效果的摄影	4:5
bioluminescent_nature	长曝光生物发光微距摄影	1:1
silhouette_shot	电影感纯黑剪影主镜头	21:9、4K

---

配置

变量	默认值	描述
GEMINI_API_KEY	—	必填。 Google Gemini API 密钥
OUTPUT_DIR	~/gemini_images	图片保存目录
DEFAULT_IMAGE_SIZE	2K	默认分辨率（1K、2K、4K）
DEFAULT_MODEL	gemini-3-pro-image-preview	默认模型
ENABLE_PROMPT_ENHANCEMENT	false	默认自动优化提示词
ENABLE_GOOGLE_SEARCH	false	默认启用 Google Search grounding
REQUEST_TIMEOUT	60	API 超时时间（秒）
MAX_BATCH_SIZE	8	批处理模式下的最大并行请求数
LOG_LEVEL	INFO	日志级别

---

故障排除

spawn uvx ENOENT — Claude Desktop 找不到 uvx。请使用完整路径：

"command": "/Users/yourusername/.local/bin/uvx"

使用以下命令查找：which uvx

GEMINI_API_KEY not found — 在 MCP 配置的 env 块或 .env 文件中设置密钥。前往 Google AI Studio 获取免费密钥。

Content blocked by safety filters — 重新措辞提示词，避免包含敏感内容。

Rate limit exceeded — 等待后重试，或升级 API 配额。

图片未保存 — 检查 OUTPUT_DIR 是否存在且可写：mkdir -p /your/output/path。

---

许可证

MIT — 详情请参阅 LICENSE。

MCP 注册表

mcp-name: io.github.nikships/ultimate-image-gen-mcp

链接

• Google AI Studio — 获取 API 密钥
• Gemini API 文档
• Model Context Protocol
• FastMCP