基于 Gemini 原生图像能力的 MCP Server 实现：从智能路由到 4K 输出的工程实践

前言

MCP（Model Context Protocol）生态爆发式增长，但图像生成领域的 MCP 实现普遍存在几个问题：

单一模型绑定：要么只接 DALL-E，要么只接 Stable Diffusion，缺乏灵活性
分辨率天花板：大多数实现止步于 1024px
上下文割裂：生成的图片无法在对话流中直接使用

基于这些痛点，我开发了 Banana Image MCP——一个支持智能模型路由、4K 原生输出、Google Search Grounding 的生产级 MCP Server。

本文分享整个工程实现过程中的技术决策与踩坑经验。

架构设计

整体分层

banana_image_mcp/
├── server.py              # 入口 + FastMCP 应用工厂
├── core/                  # 核心抽象层
│   ├── server.py          # BananaImageMCP 封装
│   ├── exceptions.py      # 统一异常体系
│   └── validation.py      # 参数校验
├── services/              # 业务逻辑层
│   ├── model_selector.py  # 智能路由核心
│   ├── pro_image_service.py
│   ├── flash_image_service.py
│   ├── base_image_service.py
│   └── gemini_client.py   # API 封装
├── tools/                 # MCP Tool 实现
│   └── generate_image.py
├── config/                # 配置管理
│   └── settings.py        # Pydantic Settings
└── prompts/               # Prompt 模板库
    ├── photography.py
    ├── design.py
    └── editing.py

设计原则：服务层与工具层解耦。MCP Tool 只负责参数解析和响应封装，业务逻辑全部下沉到 Service。

这样做的好处是，即使脱离 MCP 协议，Service 层也可以独立测试和复用。

模型路由：不只是 if-else

Gemini 图像生成有两个模型：

Flash (gemini-2.0-flash-exp)：快，2-3s，最高 1024px
Pro (gemini-2.0-flash-preview-image-generation)：慢，5-8s，最高 3840px，支持 Grounding

简单的做法是让用户手动选择，但这把复杂度暴露给了用户。

我的方案是实现一个 基于 prompt 语义分析的路由器：

class ModelSelector:
    def _auto_select(self, prompt: str, **kwargs) -> ModelTier:
        quality_score = 0
        speed_score = 0
        prompt_lower = prompt.lower()

        # 1. 关键词权重分析
        quality_keywords = ["4k", "professional", "production", "high-res", "hd"]
        speed_keywords = ["quick", "draft", "prototype", "fast", "草稿", "快速"]

        quality_score += sum(2 for kw in quality_keywords if kw in prompt_lower)
        speed_score += sum(1 for kw in speed_keywords if kw in prompt_lower)

        # 2. 参数约束强制路由
        if kwargs.get("resolution") == "4k":
            return ModelTier.PRO  # 4K 只有 Pro 支持

        if kwargs.get("enable_grounding"):
            return ModelTier.PRO  # Grounding 是 Pro 独占功能

        # 3. 批量生成倾向 Flash
        if kwargs.get("n", 1) > 2:
            speed_score += 1

        # 4. 多图 Conditioning 倾向 Pro
        input_images = kwargs.get("input_images")
        if input_images and len(input_images) > 1:
            quality_score += 1

        return ModelTier.PRO if quality_score > speed_score else ModelTier.FLASH

设计要点：

硬约束优先（4K、Grounding 直接走 Pro）
软约束打分（关键词、批量等走评分逻辑）
中文关键词支持（“草稿”、“快速”）

实际效果：用户只需要用自然语言描述需求，系统自动选择最优模型。

Google Search Grounding：被低估的杀手级功能

Grounding 是 Gemini Pro 的独占能力，但文档里几乎没有强调。

它的作用是：在生成图像时实时检索 Google 获取真实世界知识。

举个例子，当 prompt 是 “东京涩谷十字路口黄昏时分”：

无 Grounding：模型凭训练数据”想象”一个路口
有 Grounding：模型会搜索涩谷的真实照片，参考真实构图

实现上只需要在 GenerationConfig 里加一行：

from google.genai.types import GoogleSearchGrounding, GenerationConfig

generation_config = GenerationConfig(
    response_modalities=["IMAGE", "TEXT"],
    google_search_grounding=GoogleSearchGrounding(),  # 就这一行
)

但这里有个坑：Grounding 和 Flash 模型不兼容。如果用户开启了 Grounding，必须强制路由到 Pro。

4K 输出的工程细节

Pro 模型支持最高 3840px 输出，但要注意几点：

1. 分辨率映射

Gemini API 不直接接受 “4k” 这样的字符串，需要映射到具体像素值：

RESOLUTION_MAP = {
    "1k": 1024,
    "2k": 2048,
    "4k": 3840,
    "high": 2048,  # 兼容旧参数
}

2. Prompt 增强

短 prompt 在高分辨率下容易产生”空洞感”，Pro 服务会自动增强：

def _enhance_prompt(self, prompt: str, resolution: str, **kwargs) -> str:
    enhanced = prompt

    # 短 prompt 补充细节引导
    if len(prompt) < 50:
        enhanced = (
            f"Create a high-quality, detailed image: {prompt}. "
            "Pay attention to composition, lighting, and fine details."
        )

    # 4K 专属增强
    if resolution == "4k":
        enhanced += " Render at maximum 4K quality with exceptional detail."

        # 文字/图表类 prompt 强调清晰度
        if "text" in prompt.lower() or "diagram" in prompt.lower():
            enhanced += " Ensure text is sharp and clearly readable."

    return enhanced

3. 宽高比支持

4K 不只是 3840×2160，还要支持各种比例：

SUPPORTED_ASPECT_RATIOS = [
    "1:1",    # 正方形
    "16:9",   # 横屏视频
    "9:16",   # 竖屏/手机
    "4:3",    # 传统屏幕
    "3:2",    # 相机比例
    "21:9",   # 超宽屏
    "2:3", "3:4", "4:5", "5:4",
]

MCP Tool 实现：图片如何返回给 Claude

MCP 协议支持返回 Image Content，但有几个注意点：

@mcp.tool()
async def generate_image(
    prompt: str,
    model_tier: str = "pro",
    resolution: str = "4k",
    aspect_ratio: str | None = None,
    n: int = 1,
    # ...
) -> list[Content]:
    # 1. 调用 Service 生成图片
    result = await image_service.generate(prompt, **params)

    # 2. 构造 MCP 响应
    contents = []
    for image_data in result.images:
        # 图片以 base64 形式返回
        contents.append(ImageContent(
            type="image",
            data=base64.b64encode(image_data).decode(),
            mimeType="image/png",
        ))

    # 3. 附加元数据（便于追溯）
    contents.append(TextContent(
        type="text",
        text=json.dumps({
            "model": result.model_used,
            "resolution": result.actual_resolution,
            "generation_time": result.elapsed_time,
        })
    ))

    return contents

关键点：

图片必须 base64 编码
mimeType 要正确设置
附加元数据便于调试和追溯

配置管理：Pydantic Settings 最佳实践

from pydantic_settings import BaseSettings

class GeminiConfig(BaseSettings):
    api_key: str = Field(alias="GEMINI_API_KEY")

    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        extra="ignore",
    )

class ModelSelectionConfig(BaseSettings):
    default_tier: str = "pro"
    auto_quality_keywords: list[str] = [
        "professional", "high quality", "detailed", "4k", "hd"
    ]
    auto_speed_keywords: list[str] = [
        "quick", "fast", "draft", "prototype", "草稿", "快速"
    ]

好处：

环境变量自动绑定
类型校验
默认值管理
.env 文件支持

性能数据

在 M2 MacBook Pro 上的实测数据：

场景	模型	分辨率	耗时	文件大小
简单草稿	Flash	1024px	2.1s	~200KB
产品图	Pro	2048px	5.3s	~800KB
4K 海报	Pro	3840px	7.8s	~2.5MB
带 Grounding	Pro	2048px	6.2s	~900KB

Grounding 大约增加 1s 延迟，但图像准确度提升明显。

快速开始

安装

# 方式 1：uvx（推荐）
uvx banana-image-mcp

# 方式 2：pip
pip install banana-image-mcp

配置 Claude Desktop

{
  "mcpServers": {
    "banana-image": {
      "command": "uvx",
      "args": ["banana-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

配置文件位置：

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

获取 API Key

访问 Google AI Studio，免费申请。

与其他方案的对比

特性	Banana Image MCP	其他 MCP 图像方案	直接调 API
最高分辨率	3840px (4K)	通常 1024px	取决于 API
智能模型路由	支持	不支持	需自己实现
Google Grounding	支持	不支持	需自己实现
Claude 原生集成	MCP 协议	部分支持	无
开箱即用	2 分钟配置	参差不齐	需要开发

技术栈

FastMCP 2.11+：MCP Server 框架
google-genai 1.54+：Gemini Python SDK
Pydantic 2.0+：配置和校验
Python 3.11+：运行时

代码质量工具链：

ruff（lint + format）
mypy（类型检查）
pytest + pytest-cov（测试覆盖率 >80%）

后续计划

批量生成优化（并发调度）
图生图（Image-to-Image）
视频生成（Veo 集成）
本地模型支持（Ollama/ComfyUI）

总结

这个项目的核心价值不是”又一个图像生成工具”，而是：

智能路由：让用户用自然语言描述需求，系统自动选择最优模型
4K 原生：突破 1024px 的行业惯例
Grounding 集成：利用 Google 搜索增强图像真实性
生产级工程：完整的测试、类型检查、CI/CD

欢迎 Star、Fork、PR：github.com/zengwenliang416/banana-image-mcp

有问题欢迎在 Issues 讨论。

相关链接

GitHub: github.com/zengwenliang416/banana-image-mcp
PyPI: pypi.org/project/banana-image-mcp
MCP 协议: modelcontextprotocol.io
FastMCP: github.com/jlowin/fastmcp
Gemini API: ai.google.dev

用 Gemini 打造生产级 MCP Server：智能模型路由、Google Grounding 与 4K 原生输出