用途
mcp-alphabanana 是一个基于 Model Context Protocol（MCP）的本地服务器，用于使用 Google Gemini（Nano Banana 2 / Pro）生成图像素材。它面向 MCP 兼容的客户端与智能体工作流，满足快速图像生成、透明输出、参考图引导以及灵活交付格式等需求。其关键词包括 MCP server、Model Context Protocol、Gemini AI、图像生成、FastMCP。
主要能力
- 默认使用 Nano Banana 2.1 图像生成，并提供 Lite、Flash、Pro 等多个层级。
- 可输出透明 PNG/WebP 素材，适用于网页与游戏管线。
- 支持使用本地参考图像文件进行多图风格引导。
- 输出方式灵活：文件、base64 或二者组合，适配智能体工作流。
- 支持高级控制项：grounding（含 Google Search grounding）与 thinking 模式，返回 grounding 与 reasoning 元数据。
- 支持多图推理（最多 14 张参考图）。
- 提供灵活的缩放模式：crop、stretch、letterbox、contain。
- 采用 FastMCP 3 构建，代码库更简洁、输出选项更灵活。
模型层级
- NanoBanana2.1（默认，gemini-nano-banana-2.1，支持 1K/2K/4K 输出）
- Nano Banana 2 Lite（Lite3.1）：超快、成本友好的仅 1K 模型，适合快速草稿与低延迟迭代
- Flash3.1（已弃用）
- Lite3.1
- Flash2.5
- Pro3
- 以及别名 flash、pro
使用方式
运行 MCP 服务器可使用 npx，或将其加入 MCP 配置。启动服务器前必须设置 GEMINI_API_KEY。
Claude Desktop 用户可下载 mcp-alphabanana-latest.mcpb，然后在 Claude Desktop 设置的 Extensions 中添加。Windows 平台建议增加 'FileSystem' 扩展，以便更好地处理本地文件。
稳定的 MCPB 下载地址：https://github.com/tasopen/mcp-alphabanana/releases/latest/download/mcp-alphabanana-latest.mcpb
带版本号的 MCPB 地址格式：https://github.com/tasopen/mcp-alphabanana/releases/download/vVERSION/mcp-alphabanana-VERSION.mcpb
Claude Registry / MCPB 包元数据定义在 manifest.json 中，并随附静态 512x512 图标 images/mcp-alphabanana.png。原生 sharp 运行时包被声明为可选依赖，使 .mcpb 安装在受支持平台上无需依赖 postinstall 钩子即可解析正确的预构建二进制文件。
generate_image 工具参数
该工具使用 Google Gemini 生成图像，可选透明、本地参考图、grounding 与推理元数据。
关键参数：
- prompt（string）：要生成图像的描述
- model：NanoBanana2.1（默认）、Flash3.1（已弃用）、Lite3.1、Flash2.5、Pro3，以及别名 flash、pro
- outputWidth 与 outputHeight：正常模式下请求的最终图像像素尺寸
- noresize + aspectRatio + output_resolution：返回 Gemini 原生尺寸而不缩放
- output_resolution：1K、2K、4K
- output_format：png、jpg、webp
- outputType：file、base64、combine
- outputPath：当 outputType 为 file 或 combine 时必填
- transparent：启用透明 PNG/WebP 后处理
- referenceImages：可选的本地参考图像文件数组
- grounding_type 与 thinking_mode：高级 Gemini 控制项（thinking_mode：minimal / medium / high，默认 medium）
对 Claude Desktop，中大型图像建议使用 outputType=file；base64 与 combine 响应会消耗 Claude 上下文并可能触及客户端大小限制。在 Windows 上，使用 FileSystem 扩展选择可写的绝对 outputPath 以及本地 referenceImages 路径。
透明与输出格式
- PNG：完整 alpha，颜色键 + despill
- WebP：完整 alpha，压缩更好
- JPEG：不支持透明（回退为纯色背景）
Nano Banana 2.1 不提供原生透明输出。当指定 transparent=true 时，mcp-alphabanana 会执行本地后处理以生成 alpha 通道。
配置
在 MCP 配置（例如 mcp.json）中配置 GEMINI_API_KEY。可以引用操作系统环境变量，也可以直接在 mcp.json 中提供密钥。
VS Code 集成：将配置加入 VS Code 设置（.vscode/settings.json 或用户设置），在 mcp.json 或通过 VS Code MCP 设置配置服务器 env。可选：在 env 对象中添加 MCP_FALLBACK_OUTPUT 设置写入失败时的自定义回退目录。
适用场景与限制
适用于需要快速生成图像素材、透明素材、参考图引导以及可编程交付格式的 MCP 客户端与智能体工作流。使用前需具备 Google Gemini 的 GEMINI_API_KEY；透明输出依赖本地后处理而非模型原生能力；JPEG 格式不支持透明；部分模型层级（如 Flash3.1）已被标记为弃用。0.5K 分辨率在 v1.6.0 中已移除。
