mcp-alphabanana

npm version License: MIT

English | 日本語

mcp-alphabanana 是一个用于通过 Google Gemini 生成图像资产的模型上下文协议 (MCP) 服务器。它专为需要快速图像生成、透明输出、参考图像引导和灵活交付格式的 MCP 兼容客户端及代理工作流而构建。

关键词：MCP 服务器, 模型上下文协议, Gemini AI, 图像生成, FastMCP

核心功能：

跨 Flash 和 Pro 级别的超快速 Gemini 图像生成
适用于 Web 和游戏流水线的透明 PNG/WebP 资产输出
使用本地参考图像文件的多图像风格引导
适用于代理工作流的灵活文件、base64 或组合输出

alphabanana demo

快速开始

使用 npx 运行 MCP 服务器：

npx -y @tasopen/mcp-alphabanana

或者将其添加到您的 MCP 配置中：

{
  "mcp": {
    "servers": {
      "alphabanana": {
        "command": "npx",
        "args": ["-y", "@tasopen/mcp-alphabanana"],
        "env": {
          "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
        }
      }
    }
  }
}

在启动服务器之前设置 GEMINI_API_KEY。

对于 Claude Desktop，下载 mcp-alphabanana-latest.mcpb，然后从 Claude Desktop 设置中将其添加为扩展。对于 Windows，建议添加 'FileSystem' 扩展以获得更好的本地文件处理能力。 Download MCPB

Claude 注册表

Claude 注册表 / MCPB 包元数据定义在 manifest.json 中，并附带 images/mcp-alphabanana.png 处的静态 512x512 图标。

原生的 sharp 运行时包被声明为可选依赖项，因此 .mcpb 安装可以在每个受支持的平台上解析正确的预构建二进制文件，而无需依赖 postinstall 钩子。

稳定的 MCPB URL: https://github.com/tasopen/mcp-alphabanana/releases/latest/download/mcp-alphabanana-latest.mcpb
版本化 MCPB URL 模式: https://github.com/tasopen/mcp-alphabanana/releases/download/vVERSION/mcp-alphabanana-VERSION.mcpb
支持: GitHub Issues

MCP 服务器

此存储库提供了一个 MCP 服务器，使 AI 代理能够使用 Google Gemini 生成图像。

它可以与 MCP 兼容的客户端一起使用，例如：

Claude Desktop
VS Code MCP
Cursor

使用 FastMCP 3 构建，以实现简化的代码库和灵活的输出选项。

Glama MCP 服务器徽章：\

可用工具

generate_image

使用 Google Gemini 生成图像，支持可选的透明度、本地参考图像、溯源和推理元数据。

对于 Claude Desktop，中大型图像建议使用 outputType=file。base64 和 combine 响应会消耗 Claude 上下文，并可能达到客户端的大小限制。在 Windows 上，请使用 FileSystem 扩展来选择可写的绝对 outputPath 和任何本地 referenceImages 路径。

关键参数：

prompt (string): 要生成的图像描述
model: Flash3.1, Flash2.5, Pro3, flash, pro
outputWidth 和 outputHeight: 正常模式下请求的最终图像像素大小
noresize + aspectRatio + output_resolution: 返回 Gemini 原生大小而不进行调整
output_resolution: 0.5K, 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 3.1 控制

模型选择

输入模型 ID	内部模型 ID	描述
`Flash3.1`	`gemini-3.1-flash-image-preview`	超快，支持思考/溯源。
`Flash2.5`	`gemini-2.5-flash-image`	旧版 Flash。高稳定性。低成本。
`Pro3`	`gemini-3.0-pro-image-preview`	高保真 Pro 模型。
`flash`	`gemini-3.1-flash-image-preview`	向后兼容的别名。
`pro`	`gemini-3.0-pro-image-preview`	向后兼容的别名。

参数

generate_image 工具的完整参数参考。

参数	类型	默认值	描述
`prompt`	string	必需	要生成的图像描述
`outputFileName`	string	必需	输出文件名（如果缺少，自动添加扩展名）
`outputType`	enum	`combine`	`file`, `base64`, 或 `combine`
`model`	enum	`Flash3.1`	模型: `Flash3.1`, `Flash2.5`, `Pro3`, `flash`, `pro`
`output_resolution`	enum	auto	`0.5K`, `1K`, `2K`, `4K`; 当 `noresize=true` 时必需
`noresize`	boolean	`false`	跳过生成后调整大小并返回 Gemini 原生尺寸
`aspectRatio`	enum	可选	当 `noresize=true` 时必需；例如 `1:1`, `16:9`, `4:5`
`outputWidth`	integer	除非 `noresize=true` 否则必需	最终输出宽度（像素）
`outputHeight`	integer	除非 `noresize=true` 否则必需	最终输出高度（像素）
`output_format`	enum	`png`	`png`, `jpg`, `webp`
`outputPath`	string	`file` / `combine` 必需	绝对输出目录路径
`transparent`	boolean	`false`	透明背景（仅限 PNG/WebP）
`transparentColor`	string 或 null	`null`	用于透明度提取的颜色键覆盖
`colorTolerance`	integer	`30`	透明度颜色匹配容差
`fringeMode`	enum	`auto`	`auto`, `crisp`, `hd`
`resizeMode`	enum	`crop`	`crop`, `stretch`, `letterbox`, `contain`
`grounding_type`	enum	`none`	`none`, `text`, `image`, `both` (仅限 Flash3.1)
`thinking_mode`	enum	`minimal`	`minimal`, `high` (仅限 Flash3.1)
`include_thoughts`	boolean	`false`	启用元数据时返回模型推理字段
`include_metadata`	boolean	`false`	在 JSON 输出中包含溯源和推理元数据
`referenceImages`	array	`[]`	最多 14 个本地参考文件 (Flash3.1/Pro3)，Flash2.5 为 3 个
`debug`	boolean	`false`	保存中间调试工件

为什么选择 alphabanana？

零水印： API 原生纯净图像。
思考/溯源支持： 更高的提示词遵循度和基于搜索的准确性。
生产就绪： 支持透明 WebP 和精确的宽高比，适用于 Web 和游戏资产。

特性

超快速图像生成 (Gemini 3.1 Flash, 0.5K/1K/2K/4K)
高级多图像推理 (最多 14 张参考图像)
思考/溯源支持 (仅限 Flash3.1)
透明 PNG/WebP 输出 (颜色键后处理，去溢色)
多种输出格式：文件、base64 或两者兼有
灵活的调整大小模式：裁剪、拉伸、信箱、包含
多个模型级别：Flash3.1, Flash2.5, Pro3, 旧版别名

示例输出

这些示例输出是使用 mcp-alphabanana 生成并存储在 images/examples 中的。

像素艺术资产	参考图像游戏场景	照片级真实感生成

配置

在您的 MCP 配置（例如 mcp.json）中配置 GEMINI_API_KEY。

示例：

从 mcp.json 引用 OS 环境变量：

{
  "env": {
    "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
  }
}

直接在 mcp.json 中提供密钥：

{
  "env": {
    "GEMINI_API_KEY": "your_api_key_here"
  }
}

VS Code 集成

添加到您的 VS Code 设置（.vscode/settings.json 或用户设置）中，在 mcp.json 中或通过 VS Code MCP 设置配置服务器 env。

{
  "mcp": {
    "servers": {
      "mcp-alphabanana": {
        "command": "npx",
        "args": ["-y", "@tasopen/mcp-alphabanana"],
        "env": {
          "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
        }
      }
    }
  }
}

可选： 通过将 MCP_FALLBACK_OUTPUT 添加到 env 对象，为写入失败设置自定义回退目录。

使用示例

基本生成

{
  "prompt": "A pixel art treasure chest, golden trim, wooden texture",
  "model": "Flash3.1",
  "outputFileName": "chest",
  "outputType": "base64",
  "outputWidth": 64,
  "outputHeight": 64,
  "transparent": true
}

不调整大小的原生尺寸

{
  "prompt": "A clean app icon with a banana mascot, flat graphic design",
  "model": "Flash3.1",
  "outputFileName": "banana-icon-native",
  "outputType": "base64",
  "noresize": true,
  "aspectRatio": "1:1",
  "output_resolution": "0.5K",
  "output_format": "png"
}

此模式返回请求比例和分辨率的 Gemini 原生像素大小。例如，1:1 + 0.5K 返回 512x512 而无需任何调整大小步骤。

高级（垂直海报和思考）

{
  "prompt": "A vertical, photorealistic travel poster advertising Magical Wings Day Tours. A joyful young couple flies high above a breathtaking European countryside at golden hour, holding hands as they soar through a partly cloudy sky. Below them are vineyards, villages, forests, a winding river, and a hilltop medieval castle. The poster uses large, elegant typography with the headline FLY THE COUNTRYSIDE at the top and Magical Wings Day Tours branding near the bottom.",
  "model": "Flash3.1",
  "output_resolution": "1K",
  "outputFileName": "photoreal-travel-poster",
  "outputType": "file",
  "outputPath": "/path/to/output",
  "outputWidth": 848,
  "outputHeight": 1264,
  "output_format": "jpg",
  "thinking_mode": "high",
  "include_metadata": true
}

溯源示例（基于搜索）

{
  "prompt": "A modern travel poster featuring today's weather and skyline highlights in Kuala Lumpur",
  "model": "Flash3.1",
  "outputFileName": "kl_travel_poster",
  "outputType": "base64",
  "outputWidth": 1024,
  "outputHeight": 1024,
  "grounding_type": "text",
  "thinking_mode": "high",
  "include_metadata": true,
  "include_thoughts": true
}

此示例启用 Google 搜索溯源，并在 JSON 中返回溯源和推理元数据。

使用参考图像

{
  "prompt": "Use the reference image to create a game screen showing an opened treasure chest filled with coins and treasure, 8-bit dungeon crawler style, after-battle reward scene, dungeon corridor background, four-party status UI at the bottom",
  "model": "Flash3.1",
  "output_resolution": "0.5K",
  "outputFileName": "reference-image-dungeon-loot",
  "outputType": "file",
  "outputPath": "/path/to/output",
  "outputWidth": 600,
  "outputHeight": 448,
  "output_format": "webp",
  "transparent": false,
  "referenceImages": [
    {
      "description": "Treasure chest style reference",
      "filePath": "/path/to/references/pixel-art-treasure-chest.png"
    }
  ]
}

透明度与输出格式

PNG: 全 Alpha 通道，颜色键 + 去溢色
WebP: 全 Alpha 通道，更好的压缩 (Flash3.1+)
JPEG: 无透明度（回退到纯色背景）

开发

# Development mode with MCP CLI
npm run dev

# MCP Inspector (Web UI)
npm run inspect

# Build for production
npm run build

许可证

MIT

mcp-alphabanana

mcp-alphabanana

快速开始

Claude 注册表

MCP 服务器

可用工具

generate_image

模型选择

参数

为什么选择 alphabanana？

特性

示例输出

配置

VS Code 集成

使用示例

基本生成

不调整大小的原生尺寸

高级（垂直海报和思考）

溯源示例（基于搜索）

使用参考图像

透明度与输出格式

开发

许可证

Resources

Tools

Latest Blog Posts

MCP directory API