1. 项目概述与核心价值如果你和我一样日常重度依赖 Claude Desktop、Cursor 这类 AI 编程助手那你肯定遇到过这样的场景在讨论一个复杂的 UI 设计或者想为一个新项目构思 Logo 时你希望助手能直接“画”出来给你看而不是仅仅用文字描述。传统的做法是你得手动打开 Midjourney 或 Stable Diffusion 的 Web 界面把提示词复制过去生成后再把图片链接贴回来流程被切得七零八落体验非常割裂。这正是kevinten-ai/mcp-image-gen这个项目要解决的核心痛点它通过Model Context Protocol将 Google 的 Gemini 和 Imagen 系列图像生成模型无缝集成到了你的 AI 工作流中。简单来说mcp-image-gen是一个 MCP 服务器。MCP 你可以理解为一个“插件协议”它允许像 Claude、Cursor 这样的 AI 客户端去调用外部工具。这个服务器封装了 Google AI Studio免费和 Vertex AI付费的图像生成、编辑和超分辨率能力。安装配置好后你只需要在聊天窗口里对 Claude 说一句“生成一张黎明时分飞越群山的巨龙图片”它就能在对话中直接调用这个工具生成图片并展示给你同时自动保存到本地。整个过程无需离开你正在编码或思考的界面实现了真正的“所想即所得”。这个项目的价值远不止是“又一个 AI 画图工具”。首先它统一了入口把文本生成、图像编辑如局部重绘、背景替换、图像放大这三个常用功能通过三个清晰的工具generate_image,edit_image,upscale_image暴露出来你不需要记住不同平台的不同操作。其次它智能适配后端无论是使用免费的 AI Studio API Key还是需要更高画质和编辑功能的 GCP Vertex AI它都能通过环境变量轻松切换甚至支持在单次请求中动态指定使用哪个模型。最后它深度优化了开发者体验比如内置了模型选择指南MCP Resources让 AI 助手自己能读懂文档并做出最佳选择在遇到配额错误时错误信息会智能建议替代模型输出图片自动按时间戳命名归档。对于追求效率的开发者、设计师或内容创作者而言这相当于给你的 AI 副驾驶装上了一套强大的视觉化武器库。2. 架构设计与核心原理拆解要理解这个项目为何高效我们需要深入其架构。项目 README 中的架构图清晰地展示了一个简化的数据流用户提示 - AI 助手 - MCP 服务器 - Google API - 保存并显示。但在这背后服务器承担了繁重的“协议转换”和“路由分发”工作这是其设计的精妙之处。2.1 MCP 协议层标准化工具调用MCP 的核心思想是让 AI 客户端以一种标准化的方式发现和调用外部能力。mcp-image-gen服务器启动时会向客户端如 Claude Desktop宣告“我这里有三个工具可用generate_image、edit_image、upscale_image每个工具需要什么参数返回什么格式。” 客户端拿到这个“工具清单”后就能在对话中理解用户的意图并自动组装符合 MCP 规范的 JSON-RPC 请求发送给服务器。这意味着作为用户你完全不需要关心底层 HTTP API 的细节只需要用自然语言描述需求。2.2 双提供商与多模型路由机制项目最核心的复杂性在于它需要对接 Google 两套不同的 API 体系并支持众多模型。AI Studio (免费路径)使用标准的 Gemini API (generateContent)。这主要面向gemini-2.0-flash-exp-image-generation这类实验性免费模型。请求格式是围绕contents和parts构建的。Vertex AI (付费/高质量路径)使用 Vertex AI 的predictAPI。这涵盖了所有imagen-3.0-*和imagen-4.0-*系列模型以及专门的capabilityAPI用于编辑和upscaleAPI。请求格式是instances数组。服务器如何知道该走哪条路它采用了一个非常巧妙的基于模型名称前缀的路由策略。代码中会检查请求指定的model参数或默认的GEMINI_MODEL环境变量如果模型名以imagen开头则自动路由到 Vertex AI 的predict端点。否则例如gemini-开头的模型则路由到 Gemini 的generateContent端点。这种设计对上层用户和 AI 助手完全透明。你只需要关心“我要用imagen-4.0-generate-001这个模型”服务器会自动处理后续所有复杂的 API 选择和参数组装。这极大地降低了使用门槛。2.3 错误处理与用户体验优化一个健壮的工具必须能妥善处理失败。mcp-image-gen在错误处理上做了两件很棒的事智能配额错误建议Google API 的 429 错误可能有不同原因。服务器会解析错误信息如果是因为“每分钟请求数”配额超限它会在返回给客户端的错误信息中明确建议你尝试另一个模型例如从imagen-3.0-generate-002切换到imagen-3.0-fast-generate-001。因为每个模型的配额是独立的这个建议往往能立刻解决问题。内置资源文档服务器通过 MCP 的resources功能提供了guide://models和guide://providers两个内置指南。这意味着 Claude 这类助手可以在需要时主动“阅读”这些文档了解哪个模型更便宜、哪个质量更高、如何设置认证从而自主做出更优的决策减少了用户手动查阅文档的负担。这种将运维知识模型特性、配额策略和故障恢复建议直接编码到工具响应中的做法是构建“智能”工具链的关键。3. 从零开始的完整配置与实操指南理论讲完了我们动手把它装起来。我会以最常用的Claude Desktop和Cursor为例分别演示免费AI Studio和付费Vertex AI两种路径的配置。请确保你的系统已安装 Python 3.10 和uv包管理器curl -LsSf https://astral.sh/uv/install.sh | sh。3.1 方案A使用免费 AI Studio API快速上手这是零成本体验的最佳方式适合个人用户或初步探索。第一步获取 API 密钥访问 Google AI Studio 。登录你的 Google 账号。点击“创建 API 密钥”给你的密钥起个名字例如“My MCP Image Gen”。复制生成的 API 密钥字符串以AIza...开头妥善保存。第二步克隆并准备项目打开终端执行以下命令git clone https://github.com/kevinten-ai/mcp-image-gen.git cd mcp-image-gen uv syncuv sync命令会基于项目中的pyproject.toml文件创建一个独立的虚拟环境并安装所有必需依赖。这个过程通常很快。第三步配置 Claude DesktopClaude Desktop 的 MCP 服务器配置位于一个 JSON 文件中。文件位置因操作系统而异macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json你需要编辑这个文件如果不存在则创建。将以下配置块添加到mcpServers对象中。请务必将/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: AIza...替换为你的密钥 } } } }重要提示args中的--directory参数必须使用绝对路径。使用相对路径会导致 Claude Desktop 在启动时找不到服务器。你可以通过在项目目录下运行pwd命令来获取绝对路径。第四步验证与使用保存配置文件后完全重启 Claude Desktop 应用。重启后打开与 Claude 的对话你可以尝试直接说“用 mcp-image 工具生成一张赛博朋克风格的城市夜景。” 如果配置正确Claude 会识别到可用的工具并开始调用。生成的图片会以 Markdown 图片格式嵌入在回复中同时保存在项目目录下的output/文件夹里文件名类似gemini_20240321_153022.png。3.2 方案B使用 Vertex AI解锁高级功能如果你需要更高质量的 Imagen 4 模型、图像编辑或超分辨率功能或者有 Google Cloud 免费赠金就需要走 Vertex AI 路径。第一步GCP 基础设置创建或选择项目访问 Google Cloud Console 创建一个新项目或使用现有项目。记下你的项目 ID不是项目名称。启用 API 并配置账单在项目内搜索并启用“Vertex AI API”。同时确保该项目已关联一个有效的付款方式账单账户。新用户通常有 300 美元的免费赠金。创建 API 密钥进入“API 和服务” - “凭据”点击“创建凭据” - “API 密钥”。复制这个密钥。你还可以在此处限制该密钥只能调用 Vertex AI API以增强安全性。第二步安装 Vertex AI 依赖在项目目录下运行带有--extra vertex参数的同步命令这会安装google-cloud-aiplatform等额外依赖。cd /path/to/mcp-image-gen uv sync --extra vertex第三步配置 Claude Desktop (Vertex AI 版)同样编辑 Claude Desktop 的配置文件但环境变量需要调整。这里我们使用 API 密钥认证最简单{ mcpServers: { mcp-image-vertex: { command: uv, args: [ --directory, /ABSOLUTE/PATH/TO/mcp-image-gen, --extra, vertex, run, image-gen ], env: { GEMINI_PROVIDER: vertex-ai, GEMINI_API_KEY: 你的_GCP_API_密钥, GCP_PROJECT_ID: 你的-GCP-项目-ID, GCP_REGION: us-central1, GEMINI_MODEL: imagen-3.0-fast-generate-001 } } } }这里我们特意将服务器命名从mcp-image改为了mcp-image-vertex这样你可以在配置中同时保留免费版和付费版根据需要切换或同时使用。第四步体验高级功能重启 Claude Desktop 后你现在可以尝试更复杂的指令图像编辑“帮我编辑这张图片path/to/photo.jpg把背景换成海滩。”Claude 会调用edit_image工具超分辨率“将这张旧照片path/to/old.png放大 4 倍。”调用upscale_image工具指定顶级模型“用imagen-4.0-ultra-generate-001模型生成一张具有电影感的宇航员肖像。”3.3 配置 CursorCursor 的配置与 Claude Desktop 几乎完全相同因为两者都遵循 MCP 标准。Cursor 的配置文件通常位于macOS:~/Library/Application Support/Cursor/User/globalStorage/mcp.jsonWindows:%APPDATA%\Cursor\User\globalStorage\mcp.jsonLinux:~/.config/Cursor/User/globalStorage/mcp.json将上述用于 Claude Desktop 的 JSON 配置块整个放入 Cursor 配置文件的mcpServers对象内即可。同样修改后需要重启 Cursor 生效。4. 核心工具使用详解与提示词工程配置好只是开始用得好才是关键。mcp-image-gen提供的三个工具各有其适用场景和参数技巧。4.1generate_image从文本到图像这是最常用的工具。除了基本的prompt参数通过model参数动态指定模型能获得最佳效果。generate_image(prompt一位银发精灵法师在发光的森林中施展法术数字绘画风格细节丰富动态光影, modelimagen-4.0-generate-001)高质量提示词Prompt构建心法具体化主体不要只说“一只猫”。尝试“一只毛茸茸的苏格兰折耳猫睁着好奇的绿色大眼睛坐在窗台上”。定义艺术风格明确加入风格关键词如“数字绘画”、“照片写实”、“水墨风”、“吉卜力动画风格”、“低多边形建模”、“科幻概念艺术”。控制构图与镜头使用“特写镜头”、“全景景观”、“俯视视角”、“对称构图”、“黄金分割”等词汇引导画面布局。描述光影与氛围“戏剧性的侧光”、“柔和的漫射光”、“霓虹灯赛博朋克夜景”、“雾蒙蒙的清晨”。负面提示间接虽然工具不直接支持negative_prompt参数但你可以在提示词末尾加入“没有文字没有水印没有畸形的手”来规避常见问题。模型选择策略快速构思/迭代gemini-2.0-flash-exp-image-generation(免费) 或imagen-3.0-fast-generate-001(低成本)。最佳质量/成本平衡imagen-4.0-generate-001。这是目前性价比之王画质显著提升。追求极致细节imagen-4.0-ultra-generate-001。用于最终成品或对细节有严苛要求的场景。4.2edit_image精准的图像操控这个工具功能强大但依赖于 Vertex AI 的imagen-3.0-capability-001模型。其核心是edit_mode参数inpainting(默认)局部重绘。你需要提供一张图片 (image_path) 和一个掩码图 (mask_path)。掩码图中白色区域代表需要被重新生成的部分。例如你可以把照片中一个不想要的物体涂白然后提示“移除这个物体”。outpainting画面扩展。同样需要原图和掩码但掩码区域在原图边界之外用于扩展画布。提示词如“将天空扩展到上方加入更多云彩”。product-image产品图背景替换。自动识别前景主体并替换背景。提示词如“将背景换成纯白色摄影棚背景”。实操示例去除图片中路人甲用任何图片编辑工具如 Photoshop、GIMP甚至简单的在线工具打开你的原图photo.jpg。创建一个相同尺寸的纯黑图片作为掩码图mask.png。在mask.png上用纯白色画笔精确涂满你想移除的“路人甲”区域。调用工具edit_image(image_pathphoto.jpg, mask_pathmask.png, prompt移除人物只留下干净的街道, edit_modeinpainting)注意掩码的精度直接影响效果。粗糙的掩码会导致生成内容与周围区域融合不自然。4.3upscale_image提升图像分辨率这个工具使用imagen-4.0-upscale-preview模型能将图像放大 2 倍或 4 倍同时利用 AI 补充细节比传统的双线性插值算法效果好得多。upscale_image(image_pathlow-res-logo.png, upscale_factorx4)它非常适合处理老照片、网络下载的低分辨率素材或者为generate_image生成的图片默认分辨率可能不高进行二次增强。5. 高级配置、故障排查与性能调优当项目稳定运行后你会需要一些进阶技巧来应对复杂场景和问题。5.1 环境变量深度配置除了基础的 API 密钥和项目 ID以下环境变量能帮你精细化控制行为IMAGE_OUTPUT_DIR自定义输出目录。建议设置为一个绝对路径的固定文件夹方便集中管理所有 AI 生成的图片。例如--env IMAGE_OUTPUT_DIR/Users/YourName/AI_Images。GEMINI_MODEL设置全局默认模型。如果你绝大部分时间都在使用 Vertex AI 的某个特定模型可以在这里设置避免每次调用都指定model参数。例如--env GEMINI_MODELimagen-4.0-generate-001。HTTP_PROXY/HTTPS_PROXY如果你的网络环境需要代理才能访问 Google 服务可以通过这些标准环境变量配置。服务器底层使用httpx库会自动识别这些变量。一个完整的、生产环境倾向的配置示例Claude Desktop JSON 片段{ command: uv, args: [ --directory, /Users/Dev/mcp-image-gen, --extra, vertex, run, image-gen ], env: { GEMINI_PROVIDER: vertex-ai, GEMINI_API_KEY: AIza..., GCP_PROJECT_ID: my-ai-project-123, GCP_REGION: asia-northeast1, GEMINI_MODEL: imagen-4.0-generate-001, IMAGE_OUTPUT_DIR: /Users/Dev/AI_Output, HTTPS_PROXY: socks5://127.0.0.1:1080 } }5.2 系统化故障排查指南即使配置正确在实际使用中也可能遇到各种问题。下面是一个系统化的排查清单现象可能原因排查步骤Claude 完全无法识别工具MCP 服务器未成功启动或配置错误1. 检查 JSON 配置路径和格式是否正确。2. 在终端手动进入项目目录运行uv run image-gen看服务器能否独立启动并打印日志如“Server started”。3. 查看 Claude Desktop/Cursor 的日志文件通常有debug.log搜索错误信息。调用工具后返回“权限错误”API 密钥无效或权限不足1.AI Studio确认密钥是从 AI Studio 页面创建且未设置过严苛的 HTTP 引用限制。2.Vertex AI确认在 GCP 控制台已启用 Vertex AI API且该 API 密钥对当前项目有权限。错误信息包含“quota exceeded”触发 API 配额限制1.AI Studio免费配额有每日限制通常需要等待次日重置。2.Vertex AI这是最常见的问题。按照第 5.3 节的详细流程申请提升配额。生成图片失败返回“No image generated”提示词触发了内容安全策略或模型无法理解1. 尝试更简单、更具体的提示词。2. 避免可能涉及暴力、成人等敏感内容的关键词。3. 某些免费模型如gemini-2.0-flash-exp-*的审查更严格可尝试切换到 Vertex AI 模型。编辑或放大功能报“模型不支持”未使用 Vertex AI 提供商确认GEMINI_PROVIDER已设置为vertex-ai且已安装--extra vertex依赖。连接超时 (Timeout)网络问题或代理配置错误1. 检查本地网络。2. 如果使用代理确认HTTPS_PROXY环境变量设置正确且代理服务本身工作正常。5.3 Vertex AI 配额管理与成本控制对于频繁使用 Vertex AI 的用户配额和成本是两大核心关注点。配额提升申请解决 429 错误访问 GCP 配额控制台 。在筛选器中选择“服务”为Vertex AI API“指标”为Online prediction requests per base model per minute。你会看到一个列表显示每个模型每分钟的请求配额例如imagen-3.0-generate默认可能是 5 或 10。选中你需要提升的模型配额项点击“编辑配额”。在申请表中合理填写你希望的新限额例如从 10 提升到 60并简要说明用途如“用于 AI 辅助开发与设计需要更高并发”。提交申请。审批速度可能从几小时到几天不等GCP 团队可能会通过邮件与你沟通。成本优化技巧设置预算预警在 GCP 控制台的“预算与提醒”中为你的项目设置月度预算和提醒阈值例如达到 50%、90% 时发送邮件避免意外开销。善用免费额度新项目有 300 美元赠金足够进行大量实验。模型成本意识imagen-4.0-generate-001($0.02/张) 是画质和成本的绝佳平衡点。imagen-3.0-fast-generate-001($0.02/张) 速度更快适合快速迭代。imagen-4.0-ultra-generate-001($0.06/张) 仅在最终出图时使用。编辑 (imagen-3.0-capability-001) 和放大操作也单独计费。动态模型切换养成在提示中指定模型的习惯。对于草图构思用快速/廉价模型对于最终成品再切换到高质量模型。让 AI 助手Claude根据你的描述自动选择模型正是本项目 MCP Resources 设计的初衷。6. 开发与扩展深入项目内部如果你不满足于使用还想了解其内部机制或进行二次开发这里有一些指引。6.1 项目结构与代码导读克隆项目后其核心结构如下mcp-image-gen/ ├── src/mcp_image_gen/ │ ├── __init__.py │ ├── server.py # MCP 服务器主逻辑工具注册与路由 │ ├── clients.py # 封装了与 Google AI Studio Vertex AI 的通信客户端 │ ├── models.py # 数据模型请求/响应结构 │ └── utils.py # 辅助函数如图片保存、错误处理 ├── pyproject.toml # 项目依赖和元数据 ├── .env.example # 环境变量示例 └── README.md # 项目文档入口点uv run image-gen命令会调用src/mcp_image_gen/__main__.py或通过pyproject.toml定义的脚本最终启动server.py中的main()函数。核心逻辑server.py中的ImageGenMCPServer类继承自mcp.Server在__init__方法中通过self.tool()装饰器注册了三个工具函数。每个工具函数负责解析参数调用clients.py中相应的客户端方法。客户端抽象clients.py是精华所在。GoogleAIClient基类定义了通用接口AIStudioClient和VertexAIClient分别实现。特别是_route_request方法实现了我们之前分析的基于模型前缀的路由逻辑。6.2 本地调试与 MCP Inspector开发或排查复杂问题时可以使用官方 MCP Inspector 来独立测试服务器无需通过 Claude 或 Cursor。首先全局安装 Inspectornpm install -g modelcontextprotocol/inspector然后在项目目录下启动服务器并通过 Inspector 连接cd /path/to/mcp-image-gen npx modelcontextprotocol/inspector uv run image-genInspector 会启动一个本地 Web 界面通常为http://localhost:5173。在界面中你可以直接调用listTools查看服务器提供的工具。手动构造参数调用callTool模拟 AI 客户端的请求。实时查看原始的 JSON-RPC 请求和响应这对于调试参数格式错误或 API 返回的异常信息至关重要。6.3 扩展思路添加新提供商或功能这个项目的架构是高度模块化的易于扩展添加新模型提供商如果你想接入 Stability AI 或 OpenAI 的 DALL-E只需在clients.py中创建一个新的StabilityAIClient类实现相同的接口并在服务器初始化时根据配置条件选择使用哪个客户端。添加新工具例如想添加一个“图片风格迁移”工具。只需在server.py中定义一个新的工具函数def transfer_style(...)并在__init__中注册它。然后在客户端实现具体的 API 调用逻辑。修改输出处理目前图片保存到本地。你可以修改utils.py中的save_image函数将图片同时上传到云存储如 S3、Cloudinary并返回 CDN 链接或者自动压缩优化。一个简单的扩展示例为生成的图片自动添加水印。你可以在utils.py中创建一个add_watermark函数然后在save_image函数调用后对保存的图片文件进行水印处理。这样所有通过此服务器生成的图片都会自动带上你的标识。7. 常见问题与避坑实录在长期使用和社区交流中我积累了一些官方文档可能没明确写但实际会踩到的“坑”。问题一Claude Desktop 配置修改后不生效。这是最常见的问题。切记修改claude_desktop_config.json后必须完全退出 Claude Desktop 应用不是关闭窗口而是从任务栏/程序坞彻底退出再重新启动。因为 MCP 服务器列表只在应用启动时加载一次。问题二使用 Vertex AI 时错误提示“API keys not supported”。这是因为你尝试用 API 密钥去调用一个只支持应用默认凭证Application Default Credentials, ADC的模型或操作。解决方案在终端运行gcloud auth application-default login登录你的 GCP 账号然后在配置中移除GEMINI_API_KEY环境变量。服务器会优先使用 ADC。问题三生成的图片分辨率不理想。目前Google 的 Imagen/Gemini 图像生成 API 输出的分辨率是模型预定义的通常为 1024x1024、768x768 等且无法通过参数直接指定。如果你需要更高分辨率优先使用upscale_image工具进行 2x 或 4x 超分。在提示词中尝试加入“8K resolution”、“highly detailed”、“sharp focus”等词汇有时能引导模型生成更多细节尽管物理分辨率不变。对于edit_image输出分辨率与原图保持一致。问题四想批量生成图片怎么办MCP 协议设计是面向交互式对话的不适合在工具内直接做批量循环。但你可以编写一个外部 Python 脚本直接导入并使用mcp-image-gen项目中的clients.py模块进行批量调用。利用 AI 助手如 Claude的编程能力让它帮你写一个循环调用 MCP 工具的脚本。虽然效率不如直接 API 调用但在对话上下文中非常自然。问题五如何管理output/目录下越来越多的图片项目本身没有内置管理功能。建议通过IMAGE_OUTPUT_DIR环境变量将输出指向一个专门用于归档的文件夹。定期按日期或项目进行手动整理。编写一个简单的脚本利用文件名的日期时间戳自动将图片按月或按周归档到不同子文件夹中。这个项目本质上是一个精心设计的“胶水层”它弥合了强大的云端 AI 能力与我们日常使用的本地 AI 助手之间的鸿沟。它的价值不在于发明了新算法而在于通过优秀的开发者体验设计让这些能力变得触手可及。从最初的简单文本生成到现在的图像生成与编辑我的工作流已经深度依赖这类 MCP 工具。它减少了我无数次的上下文切换让我能更专注在创意和逻辑本身。如果你也厌倦了在不同标签页和工具间来回跳转不妨花半小时配置一下它可能会成为你效率工具箱中最亮眼的一件。