企业官网建设流程全解析

1. 项目概述与核心价值

如果你和我一样，日常重度依赖 Claude、Cursor 这类 AI 编程助手，那你一定遇到过这样的场景：在讨论一个复杂的 UI 设计或者想为文档配张图时，你只能干巴巴地用文字描述，然后手动去打开一个图像生成网站，上传、等待、下载，再把图片拖回对话窗口。这个过程不仅打断了流畅的“人机对话”心流，也让 AI 助手无法真正“看到”它自己建议的视觉成果。这正是我最初开发mcp-image-gen这个 MCP 服务器的核心驱动力——让图像生成能力无缝嵌入到你的 AI 工作流中。

简单来说，mcp-image-gen是一个遵循 Model Context Protocol 标准的服务器。它就像一座桥梁，一端连接着 Claude Desktop、Claude Code 或 Cursor 这类 MCP 客户端，另一端则连接着 Google 的 Gemini 和 Imagen 图像生成 API。通过它，你的 AI 助手可以直接调用generate_image、edit_image、upscale_image这三个工具，在你与 AI 对话的同一界面里，完成从文生图、图片编辑到超分辨率放大的所有操作。生成的图片不仅会即时显示在聊天窗口，还会自动保存到你指定的本地目录，整个过程无需你离开当前的 IDE 或聊天界面。

这个项目的核心价值在于“工作流整合”与“成本效率”。它并非又一个孤立的 AI 画图工具，而是将强大的图像生成能力变成了 AI 助手的一个“原生技能”。对于开发者、设计师、内容创作者而言，这意味着你可以在编写代码注释时让 Claude 直接生成示意图，在设计评审时让 AI 快速产出概念图，或者在处理用户反馈时直接编辑现有截图。更重要的是，它同时支持 Google AI Studio（免费额度）和 Google Cloud Vertex AI（使用 GCP 额度）两种后端，让你可以根据质量需求、预算和配额情况灵活切换，从免费试用到生产级应用都能平滑覆盖。

2. 架构设计与核心原理拆解

要理解mcp-image-gen如何工作，我们需要先拆解它的三层架构：客户端、MCP 协议层和 Google API 适配层。这能帮你明白为什么它比简单封装一个 API 调用要强大得多。

2.1 MCP 协议：能力注入的基石

Model Context Protocol 是由 Anthropic 主导的一个开放协议，旨在为 AI 助手定义一套标准化的方式来发现和使用外部工具与数据。你可以把它想象成 AI 世界的“USB 标准”。一个 MCP 服务器（如mcp-image-gen）启动后，会向连接的客户端（如 Claude Desktop）宣告：“嗨，我这里有generate_image、edit_image、upscale_image这几个工具可用，这是它们的调用格式和描述。” 客户端在初始化时读取这些信息，之后当你的对话自然触发了图像生成的需求（例如，你说“画一只猫”），客户端就能自动调用对应的工具，并将结果无缝嵌入到回复中。

这种设计带来了几个关键优势：

1. 对用户透明：你不需要记忆复杂的命令或切换应用，像和真人同事协作一样，用自然语言提出需求即可。
2. 对助手智能：Claude 等模型能理解工具的用途和参数，甚至能根据guide://资源（服务器提供的文档）来智能选择最适合的模型。
3. 标准化与生态：任何兼容 MCP 的客户端都能使用这个服务器，促进了工具生态的繁荣。

2.2 双后端适配：统一接口下的复杂调度

项目最精妙的设计之一，在于用一套统一的工具接口，封装了 Google 两套不同的图像生成 API 体系。这是通过一个内部的路由器（Router）实现的。

Gemini GenerateContent API：主要用于gemini-2.0-flash-exp-image-generation这类模型。它的请求体结构是围绕“多轮对话”设计的，图像生成请求被放在contents[].parts[].text字段中。AI Studio 免费额度主要走这个 API。

Imagen Predict API：用于imagen-3.0-*和imagen-4.0-*系列模型。这是 Vertex AI 的标准预测接口，请求体格式为instances[].prompt。此外，专用的编辑模型 (imagen-3.0-capability-001) 和超分模型 (imagen-4.0-upscale-preview) 也使用 Predict API，但请求结构略有不同（例如，编辑需要传入referenceImages）。

mcp-image-gen服务器在收到请求后，会首先解析model参数（或使用默认的GEMINI_MODEL）。如果模型名以imagen开头，则自动路由到 Predict API 的处理逻辑；否则，路由到 GenerateContent API。同时，它还会根据操作类型（生成、编辑、超分）和使用的具体模型，动态构建符合对应 API 要求的 JSON 请求体。这种设计对使用者完全隐藏了复杂性，你只需要关心“我想用什么模型生成什么”，而不需要知道背后是哪个 API、该如何构造请求。

2.3 错误处理与智能降级

在实际使用中，API 配额限制（429 错误）是最常见的问题。mcp-image-gen在这方面做了贴心的设计。它不仅会返回明确的错误信息，还会在错误响应中直接“建议”可替代的模型。例如，当imagen-3.0-generate-002因每分钟请求数（QPM）配额用尽而报错时，服务器的错误信息会提示：“您可以尝试切换到imagen-3.0-fast-generate-001模型，它拥有独立的配额。” 这使得 AI 助手能够根据错误反馈，自动尝试另一个模型，提升了整体的鲁棒性和用户体验。

3. 环境搭建与配置实战

理论讲完，我们进入实战环节。我会以最常用的Claude Desktop + AI Studio（免费）和Cursor + Vertex AI（高质量）两种组合为例，带你一步步完成配置。

3.1 方案一：零成本快速上手（AI Studio + Claude Desktop）

这个方案适合所有想立即体验、无需支付任何费用的用户。AI Studio 提供的免费额度足以满足个人日常的探索和轻度使用。

第一步：获取 AI Studio API 密钥

1. 访问 Google AI Studio ，使用你的 Google 账号登录。
2. 点击页面上的“Create API Key”按钮。
3. 在弹出的窗口中，给你的密钥起个名字（例如mcp-image-gen），然后点击创建。
4. 重要：立即复制生成的 API 密钥并妥善保存。这个密钥只会显示一次，关闭窗口后就无法再次查看。如果丢失，需要删除旧密钥重新创建。

第二步：配置 Claude Desktop 的 MCP 设置Claude Desktop 通过一个 JSON 配置文件来管理 MCP 服务器。我们需要找到并编辑这个文件。

• macOS: 配置文件位于~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: 配置文件通常位于%APPDATA%\Claude\claude_desktop_config.json
• Linux: 配置文件位于~/.config/Claude/claude_desktop_config.json

如果该文件或目录不存在，手动创建即可。用任何文本编辑器打开这个 JSON 文件，将mcp-image-gen服务器的配置添加进去。以下是完整的配置示例，你需要将YOUR_AI_STUDIO_API_KEY替换成你刚才复制的密钥，并将/ABSOLUTE/PATH/TO/mcp-image-gen替换为你克隆项目后的绝对路径。

{ "mcpServers": { "mcp-image": { "command": "uv", "args": [ "--directory", "/ABSOLUTE/PATH/TO/mcp-image-gen", "run", "image-gen" ], "env": { "GEMINI_API_KEY": "YOUR_AI_STUDIO_API_KEY", "GEMINI_MODEL": "gemini-2.0-flash-exp-image-generation", "IMAGE_OUTPUT_DIR": "/ABSOLUTE/PATH/TO/your/image/output" } } } }

注意：args中的--directory路径必须是绝对路径，相对路径会导致 Claude Desktop 找不到服务器。IMAGE_OUTPUT_DIR也建议设置为绝对路径，方便你查找生成的图片。

第三步：验证与使用

1. 保存配置文件并完全重启 Claude Desktop 应用（重要！配置只在启动时加载）。
2. 重启后，新建一个对话。如果配置成功，Claude 的回复中不会出现任何特殊提示，但当你提出图像生成需求时，它会直接调用工具。
3. 尝试发送：“帮我生成一张宁静的日式庭院图片，有锦鲤池塘和红枫树。”
4. 稍等片刻，Claude 的回复中就会嵌入一张生成的图片。同时，你设置的IMAGE_OUTPUT_DIR目录下会多出一个类似gemini_20250321_153045.png的文件。

3.2 方案二：高质量生产级配置（Vertex AI + Cursor）

如果你需要更高质量的图像、图像编辑或放大功能，或者拥有 Google Cloud 额度，那么 Vertex AI 是更好的选择。这里以在 Cursor IDE 中集成为例。

第一步：准备 GCP 环境

1. 创建或选择项目：访问 Google Cloud Console ，创建一个新项目或选择一个现有项目。确保该项目已启用结算功能。
2. 启用 API：在项目内，搜索并启用“Vertex AI API”。
3. 创建 API 密钥：进入“API 和服务” -> “凭据”，点击“创建凭据” -> “API 密钥”。复制这个密钥，它将是你的GEMINI_API_KEY。为了安全，你可以在“限制密钥”中，将其限制为仅用于 Vertex AI API。

第二步：安装带有 Vertex AI 支持的服务器由于 Vertex AI 需要额外的认证库，我们需要在安装时指定vertex额外依赖。

# 克隆项目 git clone https://github.com/kevinten-ai/mcp-image-gen.git cd mcp-image-gen # 使用 uv 安装依赖，并指定 vertex 扩展 uv sync --extra vertex

第三步：配置 Cursor 的 MCPCursor 的 MCP 配置方式与 Claude Desktop 类似。你需要找到 Cursor 的配置目录。

• macOS:~/.cursor/mcp.json
• Windows:%APPDATA%\Cursor\mcp.json
• Linux:~/.cursor/mcp.json

同样，如果文件不存在则创建它。将以下配置添加到mcp.json中。请替换YOUR_GCP_API_KEY、your-gcp-project-id和项目路径。

{ "mcpServers": { "mcp-image": { "command": "uv", "args": [ "--directory", "/ABSOLUTE/PATH/TO/mcp-image-gen", "--extra", "vertex", "run", "image-gen" ], "env": { "GEMINI_PROVIDER": "vertex-ai", "GEMINI_API_KEY": "YOUR_GCP_API_KEY", "GCP_PROJECT_ID": "your-gcp-project-id", "GCP_REGION": "us-central1", "GEMINI_MODEL": "imagen-4.0-generate-001", "IMAGE_OUTPUT_DIR": "/ABSOLUTE/PATH/TO/your/image/output" } } } }

实操心得：GCP_REGION不是所有区域都支持最新的 Imagen 4 模型。us-central1(爱荷华) 通常是功能最全、上新最快的区域，建议优先使用。如果你在亚洲，也可以尝试asia-northeast1(东京) 或asia-southeast1(新加坡)。

第四步：测试高级功能配置完成后重启 Cursor。现在，除了生成，你还可以测试编辑和放大功能。例如，你可以准备一张图片photo.jpg和一个指定编辑区域的黑白掩码图mask.png（白色区域表示需要编辑的部分），然后对 AI 助手说： “请使用edit_image工具，以photo.jpg为原图，mask.png为掩码，使用outpainting模式，将画面向四周扩展，生成一个更广阔的风景。” AI 助手会理解你的指令并调用相应的工具完成操作。

4. 模型选择策略与提示词工程

配置好环境只是开始，用好mcp-image-gen的关键在于根据场景选择合适的模型，并掌握有效的提示词技巧。

4.1 模型选择决策树

面对多个模型，如何选择？我根据自己的使用经验，总结出以下决策流程：

1. 免费优先，快速验证：任何新想法或简单需求，首先使用 AI Studio 的gemini-2.0-flash-exp-image-generation。它是免费的，速度也快，适合头脑风暴和概念验证。
2. 追求性价比的优质输出：当需要用于文档、演示或社交媒体的高质量图片时，切换到 Vertex AI 的imagen-4.0-generate-001。它的质量显著高于免费模型，而每张图约 $0.02 的成本在商业场景下完全可以接受，是“主力模型”。
3. 追求极致质量：对于非常重要的视觉材料，如产品概念图、营销海报的核心视觉，可以使用imagen-4.0-ultra-generate-001。它的细节、光影和构图能力更强，但成本也翻了三倍（约 $0.06/张），需酌情使用。
4. 需要极速响应：在交互式场景中，如果等待时间敏感，imagen-3.0-fast-generate-001是速度最快的收费模型，质量尚可，成本与 4.0 标准版相当。
5. 遇到配额限制：这是关键技巧。Google 的配额是按每个模型单独计算的。如果你常用的imagen-4.0-generate-001报 429 配额错误，立即切换到imagen-3.0-fast-generate-001或imagen-3.0-generate-002，通常可以立即恢复使用，因为它们消耗的是另一组独立的配额。

4.2 提升出图质量的提示词技巧

AI 图像生成是“垃圾进，垃圾出”。清晰的提示词能极大提升结果质量。以下是我总结的“提示词配方”：

基础结构：[主体] + [细节描述] + [环境/背景] + [艺术风格] + [技术参数]

• 主体明确：不要说“一只狗”，要说“一只正在接飞盘的成年边境牧羊犬，动态瞬间，毛发飞扬”。
• 细节具体化：
  • 材质：磨砂玻璃、生锈的铁皮、湿润的鹅卵石。
  • 光影：午后四点的侧逆光、电影感的戏剧性灯光、柔和的漫反射光。
  • 构图：中心对称构图、黄金分割点特写、极具张力的低角度仰拍。
  • 情绪：孤独的、欢庆的、神秘的、未来感的。
• 风格指令：直接使用艺术流派或特定艺术家风格，如“赛博朋克风格”、“吉卜力工作室动画风格”、“莫奈的印象派笔触”、“科幻概念艺术，by Greg Rutkowski”。
• 负面提示：虽然工具未直接提供负面提示词参数，但你可以在正向提示词末尾加入“，没有文字，没有水印，没有扭曲的脸，没有多余的手指”，这通常能帮助模型避免一些常见缺陷。
• 利用 AI 助手优化：你可以直接对 Claude 说：“我想生成一张表现‘数字生命’的抽象画。请帮我构思一个详细、富有视觉冲击力的英文提示词，并调用generate_image工具。” Claude 本身就是一个出色的提示词工程师。

注意事项：Imagen/Gemini 对文本渲染能力较弱。如果你的场景中必须包含可读的文字（如店铺招牌、海报标题），最好在生成图像后，用其他工具（如 Photoshop）后期添加。在提示词中强调“无文字”反而能得到更干净的图。

5. 高级功能：编辑与超分详解

edit_image和upscale_image是 Vertex AI 专属的两个强大工具，它们将 AI 图像处理从“生成”延伸到了“修改”和“增强”。

5.1 图像编辑的三种模式

edit_image工具主要通过edit_mode参数来实现三种不同的编辑效果：

1. Inpainting（局部重绘）：这是最常用的模式。你需要提供一张原图和一个掩码图。掩码图是一张和原图同尺寸的黑白图，其中白色区域代表你希望 AI 重新绘制或修改的部分，黑色区域代表需要保留的部分。例如，你可以把照片中一个不想要的物体涂成白色，然后在提示词中描述你希望替换成什么。

   • 操作示例：edit_image(prompt="a beautiful flower vase", image_path="living_room.png", mask_path="object_mask.png", edit_mode="inpainting")

2. Outpainting（画幅扩展）：想象一下，你的照片构图太满，你想看到更多左右的风景。Outpainting 可以让 AI 智能地扩展图像的边界。你需要提供一个掩码图，其中白色区域表示你希望 AI新生成的扩展区域，这个区域通常在原图边界之外。原图部分在掩码中应为黑色。

   • 操作示例：edit_image(prompt="expansive cloudy sky and rolling hills", image_path="portrait.jpg", mask_path="expansion_mask.png", edit_mode="outpainting")

3. Product Image（产品图模式）：这个模式专为电商场景优化，可以智能地替换或生成纯色背景。你通常不需要提供复杂的掩码，只需一个大致勾勒出产品轮廓的掩码即可。AI 会理解主体的概念并为其生成一个干净的新背景。

   • 操作示例：edit_image(prompt="professional white studio background", image_path="product_on_desk.jpg", mask_path="product_mask.png", edit_mode="product-image")

掩码图制作技巧：你可以使用任何图像编辑软件（如 Photoshop、GIMP，甚至简单的在线工具）来创建掩码。保存为 PNG 格式以确保透明度（如果需要）。对于简单物体，用纯色画笔涂抹即可。对于复杂边缘，利用软件的“快速选择”或“魔术棒”工具选中主体，反选后填充白色作为掩码，会高效很多。

5.2 超分辨率放大实战

upscale_image工具使用imagen-4.0-upscale-preview模型，可以将图像清晰放大 2 倍或 4 倍。这对于提升低分辨率素材的可用性至关重要。

• 参数选择：upscale_factor可选"x2"或"x4"。通常建议先尝试"x2"，如果效果满意但尺寸仍不足，可以对放大后的结果再次执行"x2"放大。直接使用"x4"有时会引入更多不可控的伪影。
• 最佳实践：超分模型在处理具有清晰线条和纹理的图像（如建筑、插画）时效果最好。对于本身非常模糊或噪点严重的照片，放大效果可能有限，它会“想象”细节，可能与原图有出入。
• 工作流整合：一个典型的流程是：先用generate_image以较低分辨率（如 1024x1024）快速生成多张草图；挑选出最满意的一张后，使用upscale_image将其放大到 4K (4096x4096) 分辨率，用于高清展示或印刷。

6. 故障排查与性能优化

即使配置正确，在实际使用中也可能遇到各种问题。以下是基于大量实战经验总结的排查指南和优化建议。

6.1 常见错误与解决方案速查表

6.2 性能与成本优化技巧

1. 善用免费额度：将 AI Studio 的免费模型用于所有非关键任务的头脑风暴、草图和迭代。只有确定最终方向后，再切换到 Vertex AI 的收费模型出成图。
2. 设置默认模型：在环境变量中设置GEMINI_MODEL=imagen-3.0-fast-generate-001。这个模型速度最快，成本与高质量的 4.0 标准版相同，但在迭代速度上优势明显。需要高质量输出时，再在单次请求中通过model参数指定imagen-4.0-generate-001。
3. 监控成本：在 GCP 控制台设置预算提醒。Vertex AI 的 Imagen 模型价格透明（约 $0.02-$0.06/张），你可以根据生成数量预估月度成本。对于编辑和超分操作，也要留意其独立定价。
4. 利用 MCP 资源：服务器内置的guide://models和guide://providers资源包含了最新的模型对比和配置指南。你可以直接让 Claude 去“阅读”这些资源，让它来帮你做出最优的模型选择决策，例如：“根据guide://models里的信息，为我这个‘生成一个卡通熊猫头像’的需求选一个最省钱的模型。”

6.3 网络与代理配置

如果你在访问 Google API 时遇到网络连接超时问题，项目内置了 SOCKS 代理支持。这通过httpx库的环境变量实现，无需修改代码。

# 在启动 MCP 服务器的环境变量中配置 export HTTP_PROXY="socks5://127.0.0.1:1080" export HTTPS_PROXY="socks5://127.0.0.1:1080"

在你的 MCP 客户端配置中，可以将这些变量添加到env部分。注意，Claude Desktop 或 Cursor 的配置是 JSON 格式，你需要确保传递的是正确的字符串。

经过以上六个部分的详细拆解，你应该已经从原理到实践，全面掌握了mcp-image-gen这个强大的工具。它的本质是将专业的 AI 图像能力平民化、流程化，让你和你的 AI 助手能像一个真正的设计团队一样协作。从今天起，试着在你的下一个项目讨论、技术文档编写或创意构思中，让 Claude 或 Cursor 直接“动手”画出来吧，那种流畅的体验，绝对会让你忘记曾经在多个标签页间来回切换的繁琐。