图像生成服务器

Gemini Image Gen MCP服务器

AI image generation, editing & upscaling via Google Gemini and Imagen.
Generate, edit (inpainting), and upscale images — all through one MCP server.
Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.

中文文档

特性

• 3工具 — generate_image, edit_image （修复/外涂）， upscale_image （2x/4x）
• 双重提供者 --AI工作室（免费）或顶点AI（GCP学分）
• 多模态 --Vertex AI上的Gemini 3.1/3 Pro图像、Gemini 2.5 Flash图像和传统Imagen 4
• 动态模型切换 --根据请求选择型号 model 参数，无需重新启动
• 内置指南 --MCP资源，包括模型选择提示和提供者文档
• 智能错误恢复 --auto根据配额误差建议替代模型
• 自动将生成的图像保存到磁盘
• 开箱即用的SOCKS代理支持

演示

建筑学

User Prompt → AI Assistant (Claude / Cursor) → MCP Server → Gemini API / Vertex AI
                                                   ↓
                                             Save to disk + Display

运作原理

服务器在一个统一的接口下处理两个不同的Google API：

服务器根据型号名称前缀自动选择正确的API- imagen* 路线预测，其他一切生成内容。你不必担心这种区别。

快速开始

选项A:AI Studio（免费，建议初学者使用）

1.获取API密钥 --参观https://aistudio.google.com/apikey → 创建API密钥→ 复制它

2.配置MCP

claude mcp add --transport stdio mcp-image \
  --env GEMINI_API_KEY=your_api_key \
  -- uv --directory /path/to/mcp-image-gen run image-gen

{
  "mcpServers": {
    "mcp-image": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-image-gen", "run", "image-gen"],
      "env": {
        "GEMINI_API_KEY": "your_api_key"
      }
    }
  }
}

3.使用它 --问问你的人工智能助手：

"Generate an image of a dragon flying over mountains at dawn"

图像将内联显示并自动保存到 output/ 目录。

选项B：顶点AI（更高质量，GCP学分）

使用Gemini图像模型的GCP计费，可选的传统Imagen 4代，以及图像编辑和升级。

1.先决条件

• 启用计费的GCP项目(创建一个)
• Vertex AI API已启用(启用它)
• GCP API密钥(创建一个)

2.使用Vertex AI支架安装

git clone https://github.com/kevinten-ai/mcp-image-gen.git
cd mcp-image-gen
uv sync --extra vertex

3.配置MCP

claude mcp add --transport stdio mcp-image \
  --env GEMINI_PROVIDER=vertex-ai \
  --env GEMINI_API_KEY=your_gcp_api_key \
  --env GCP_PROJECT_ID=your-project-id \
  --env GCP_REGION=us-central1 \
  --env GEMINI_MODEL=gemini-3.1-flash-image \
  -- uv --directory /path/to/mcp-image-gen run --extra vertex image-gen

{
  "mcpServers": {
    "mcp-image": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-image-gen", "run", "--extra", "vertex", "image-gen"],
      "env": {
        "GEMINI_PROVIDER": "vertex-ai",
        "GEMINI_API_KEY": "your_gcp_api_key",
        "GCP_PROJECT_ID": "your-project-id",
        "GCP_REGION": "us-central1",
        "GEMINI_MODEL": "gemini-3.1-flash-image"
      }
    }
  }
}

身份验证选项： Vertex AI支持两种身份验证方法：

1. GCP API密钥 （推荐）--设置 GEMINI_API_KEY简单，无需额外付费。
2. OAuth2/ADC --奔跑 gcloud auth application-default login。当未设置API密钥时，服务器自动检测ADC。需要 --extra vertex 为了 google-auth 附属国。

工具

generate_image--文本到图像

根据文本提示生成图像。

"A cozy cafe in Paris at sunset"

edit_image--图像编辑（仅限顶点AI）

使用文本说明编辑现有图像。支持修复、外绘和背景交换。

edit_image(prompt="Add a red hat", image_path="/path/to/photo.png")
edit_image(prompt="Replace background with beach", image_path="photo.png", edit_mode="product-image")
edit_image(prompt="Expand the sky", image_path="photo.png", mask_path="mask.png", edit_mode="outpainting")

upscale_image--超分辨率（仅限顶点AI）

将图像放大到2倍或4倍分辨率。

upscale_image(image_path="/path/to/photo.png", upscale_factor="x4")

使用指南

获得更好结果的提示

• 具体说明：“一只金毛寻回犬在秋叶中嬉戏，柔和的自然光线”比“一只狗”效果更好
• 提及风格：添加“数字艺术”、“照片级真实感”、“水彩”、“油画”、“动漫风格”等术语
• 描述照明：“黄金时刻”、“戏剧性的灯光”、“柔和的漫射光”
• 指定组成：“特写肖像”、“广角风景”、“鸟瞰图”
• 无文字：图像模型通常难以渲染文本。在提示中使用“无文本”以获得更清晰的结果。

选择模型

按请求切换（推荐）

通过 model 调用工具时的参数：

generate_image(prompt="a sunset landscape", model="gemini-3-pro-image")

AI助手可以根据请求动态选择最佳模型。如果一个模型达到配额限制，错误响应会自动建议替代方案。

决策流程图

Need an image?
  ├─ Free / no GCP account?
  │   └─ AI Studio: gemini-3.1-flash-image ✅
  │
  └─ Have GCP billing?
      ├─ Need balanced quality/speed?
      │   └─ gemini-3.1-flash-image ✅
      │
      ├─ Need stronger reasoning/composition?
      │   └─ gemini-3-pro-image
      │
      ├─ Need to edit an image?
      │   └─ edit_image tool (uses imagen-3.0-capability-001)
      │
      ├─ Need to upscale?
      │   └─ upscale_image tool (uses imagen-4.0-upscale-preview)
      │
      └─ Hit quota on one model?
          └─ Switch to another — each model has independent quota

通过环境变量默认

集 GEMINI_MODEL 配置否时使用的默认模型 model 传递参数：

# AI Studio (Gemini models)
GEMINI_MODEL=gemini-3.1-flash-image      # default, balanced
GEMINI_MODEL=gemini-3-pro-image          # stronger reasoning/composition
GEMINI_MODEL=gemini-2.5-flash-image      # fallback

# Vertex AI (Gemini + legacy Imagen models)
GEMINI_MODEL=gemini-3.1-flash-image        # default
GEMINI_MODEL=imagen-4.0-generate-001       # legacy Imagen; retires Aug 17, 2026

MCP资源

服务器公开了AI助手可以自动读取的内置文档：

人工智能助手（Claude等）可以阅读这些资源，在没有人为干预的情况下做出明智的模型选择。

自定义输出目录

--env IMAGE_OUTPUT_DIR=/absolute/path/to/your/images

图像与时间戳一起保存： imagen_20260321_234225.png 或 gemini_20260321_234225.png.

环境变量

支持的型号

人工智能工作室（双子座）——免费

顶点AI（Imagen）——GCP学分

顶点AI——专业模型

关键洞察：每个模型都有自己独立的API配额。如果一个型号达到429，切换到另一个型号将有效，因为它们使用单独的速率限制。

故障排除

错误参考

配额和计费错误（429）

这些是最常见的错误。有 两个不同的429错误 原因不同：

429: Quota exceeded for online_prediction_requests_per_base_model

意思是： 您已经达到特定型号的API呼叫速率限制。

快速修复： 通过以下方式切换到其他型号 model 参数——每个模型都有独立的配额：

generate_image(prompt="...", model="gemini-3-pro-image")

长期修复： 请求增加配额：

1. 首选 GCP控制台→我喜欢；管理员→配额
2. 筛选依据 online_prediction_requests_per_base_model
3. 找到你的模型（例如。， gemini-3.1-flash-image 或 imagen-4.0-generate)
4. 点击 编辑配额 → 请求更高的限制（默认值通常仅为5 QPM）

429: Quota exceeded ... spending cap

意思是： 您达到了自我组合的账单支出限制，而不是API费率限制。

修复：

1. 首选 GCP控制台→ 计费→ 预算和警报
2. 找到有支出上限的预算
3. 增加或移除盖子

提示： 对于新配置，更喜欢Gemini映像模型。Imagen 4代ID仍然可用于传统的Vertex AI设置，但计划于2026年8月17日退役。

身份验证错误

模型误差

连接错误

先决条件

• Python 3.10+
• 紫外线 --安装方式 curl -LsSf https://astral.sh/uv/install.sh | sh

本地开发

git clone https://github.com/kevinten-ai/mcp-image-gen.git
cd mcp-image-gen

# Install dependencies (add --extra vertex for Vertex AI support)
uv sync

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your API key

# Run the server directly
uv run image-gen

使用MCP检查器进行调试

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-image-gen run image-gen

相关项目

• mcp视频生成器 --多提供商AI视频生成MCP服务器
• mcp-3d-gen --AI 3D模型生成MCP服务器

许可证

麻省理工学院——见 许可证 了解详情。