MCP Imagenate

mcp-imagenate

一个用于图像生成的 MCP 服务，支持多个提供商：Google Gemini、OpenAI (gpt-image)、BFL FLUX 和 Reve，还可通过 Google Gemini Omni 生成短视频片段。

提供商与模型

Google Gemini（Nano Banana）

名称	模型 ID	最适用于
nano-banana-2	gemini-3.1-flash-image-preview	快速、大批量生成
nano-banana-2.1	gemini-nano-banana-2.1	Nano Banana 2 的后继版本（仅支持 1K/2K/4K）
nano-banana-pro	gemini-3-pro-image-preview	最高质量的输出

Google Gemini Omni（视频）

名称	模型 ID	最适用于
gemini-omni-1.1-flash	gemini-omni-1.1-flash	3–10 秒、带音频且屏幕文字清晰可读的视频片段

使用相同的 GEMINI_API_KEY。通过单独的 generate_video 工具提供 — 参见 工具：generate_video。

OpenAI

名称	模型 ID	最适用于
gpt-image-2.5-flare	gpt-image-2.5-flare	快速生成，中高品质下价格低廉。本项目的默认模型
gpt-image-2.5-sunburst	gpt-image-2.5-sunburst	精细编辑，速度比 Flare 慢
gpt-image-2	gpt-image-2	上一代模型

这里仅有这些模型支持返回透明背景 — 参见 透明背景。

BFL FLUX

名称	模型 ID	最适用于
flux-2-klein	klein-4b	快速、轻量级生成
flux-2-pro	pro-preview	质量与速度均衡
flux-2-max	max	最高质量

Reve

名称	版本	最适用于
reve-image	latest	字体排版与布局还原度

此提供商调用 Reve 的 v2/image/create 端点。latest 是 v2 公开的唯一版本别名，也是响应中返回的版本，因此没有可固定到的带日期版本。不要将它与 v1 端点混淆，后者仍提供较旧的 reve-create@20250915 模型。

向 Reve 发送为其他提供商编写的提示词前，有几点值得了解：

• resolution 会被忽略 — Reve 没有尺寸参数，并会返回其自身的大尺寸输出。每次请求的确切尺寸会有所不同：16:9 曾返回 5408x3072 和 5376x3072，3:4 则返回 3456x4800。
• 提示词最多可包含 4,000 个字符；超过此长度时，此提供商会在消耗请求前拒绝处理。
• inputImages 会转换为 v2 的 references。Reve 最多接受八张图片；超过此数量时，会在读取任何文件前拒绝处理。
• 保存文件的扩展名取决于 Reve 实际返回的格式（PNG、JPEG 或 WebP），程序会根据字节内容检测格式，而非进行假设。
• 每次生成消耗 150 个点数（约 $0.20），通常需要 40-80 秒。请为前置代理或作业运行器设置至少 120 秒的超时。

要求

• Node.js 22+
• 至少一个提供商的 API 密钥

安装

npx mcp-imagenate

或全局安装：

npm install -g mcp-imagenate

设置

为要使用的提供商设置 API 密钥：

# Google Gemini (at least one)
export GEMINI_API_KEY=your_key_here
# or
export NANO_BANANA_API_KEY=your_key_here

# OpenAI (at least one)
export OPENAI_API_KEY=your_key_here
# or
export GPT_IMAGE_API_KEY=your_key_here

# BFL FLUX
export BFL_API_KEY=your_key_here

# Reve (at least one)
export REVE_API_KEY=your_key_here
# or
export REVE_API_TOKEN=your_key_here

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-imagenate": {
      "command": "npx",
      "args": ["mcp-imagenate"],
      "env": {
        "GEMINI_API_KEY": "your_key_here",
        "NANO_BANANA_OUTPUT_DIR": "/path/to/image/output"
      }
    }
  }
}

环境变量

变量	必需	说明
GEMINI_API_KEY	*	Google AI Studio API 密钥
NANO_BANANA_API_KEY	*	GEMINI_API_KEY 的替代项（优先使用）
OPENAI_API_KEY	*	OpenAI API 密钥
GPT_IMAGE_API_KEY	*	OPENAI_API_KEY 的替代项（优先使用）
BFL_API_KEY	*	BFL FLUX API 密钥
REVE_API_KEY	*	Reve 合作伙伴 API 令牌（来自 api.reve.com 的 API 控制台）
REVE_API_TOKEN	*	REVE_API_KEY 的替代项（优先使用 REVE_API_KEY）
NANO_BANANA_OUTPUT_DIR	否	保存图像的基础目录。设置后，所有输出和输入路径都限制在此目录内。建议用于生产环境。

* 必须至少设置一个提供商 API 密钥。

工具：generate_image

参数

参数	类型	默认值	说明
prompt	string（1-32,000 个字符）	-	描述图像的文本提示词
model	见上文“模型”	"gpt-image-2.5-flare"	要使用的模型（可用模型取决于已配置的 API 密钥）
resolution	"1K" | "2K" | "4K"	"1K"	输出图像分辨率
aspectRatio	见下文	"1:1"	图像的宽高比
mode	"image" | "image_and_text"	"image"	仅返回图像，或返回图像及其描述（仅限 Google 模型）
background	"auto" | "transparent" | "opaque"	"auto"	图像所处的背景。"transparent" 需要 gpt-image 模型——见下文
thinking	"none" | "auto"	"auto"	控制模型思考（仅限 Google 模型）
outputDir	string	"."	保存图像的目录
inputImages	string[]	-	与提示词一同发送的图像文件路径（Google 模型、通过 images.edit 端点使用的 OpenAI gpt-image 模型，以及通过 v2 references 使用的 Reve）

支持的宽高比

1:1、2:3、3:2、3:4、4:3、9:16、16:9、21:9

透明背景

background: "transparent" 会保存带有 Alpha 通道的 PNG，适合抠出主体并将其放到幻灯片上或另一张图片上。

只有 OpenAI gpt-image 模型支持此功能。若要求其他模型（nano-banana-*、flux-2-*、reve-image）生成透明背景，会报错，而不是悄悄返回不透明图片——请求会在发送前被拒绝，因此不会产生费用。即使在提示词中写入“透明背景”也无济于事：这些提供商根本没有透明模式。

"opaque" 会强制所有读取该字段的提供商填充背景，而默认值 "auto" 则将选择权留给模型，这也是此服务一直以来的行为。

响应

返回一个 JSON 对象：

{
  "model": "gemini-3.1-flash-image-preview",
  "savedFiles": ["/path/to/image-1.png"],
  "settings": {
    "resolution": "1K",
    "aspectRatio": "9:16",
    "mode": "image",
    "background": "auto"
  },
  "description": "..."
}

仅当 mode 为 "image_and_text" 时，才会包含 description。

工具：generate_video

配置 Google 密钥后即可使用。生成一个带音频的视频片段，并将其保存为 mp4。

参数

参数	类型	默认值	描述
prompt	string (1-32,000 chars)	-	主体、动作、镜头，以及需要准确呈现的屏幕文字
model	"gemini-omni-1.1-flash"	"gemini-omni-1.1-flash"	要使用的视频模型
durationSeconds	integer 3–10	5	视频片段时长。费用和生成时间均随秒数增加（5 秒约需 1 分钟，10 秒约需 2 分钟）
resolution	"360p" | "720p" | "1080p" | "4k"	"720p"	播放分辨率。360p 成本最低、速度最快；1080p 和 4k 均由 720p 放大而来
aspectRatio	"16:9" | "9:16"	"16:9"	横向或纵向
outputDir	string	"."	保存视频片段的目录（沙盒限制与 generate_image 相同）
inputImages	string[]	-	在提示词之前发送的参考图片：用于生成动画的首帧，或需要保留的主体和风格。可通过 <IMAGE_REF_1>、<IMAGE_REF_2> 等引用
previousInteractionId	string	-	之前结果中的 interactionId。基于该视频片段继续生成，而不是开始新片段；提示词描述接下来发生的内容

值得了解的事项：

• 模型将单次请求的时长限制为 10 秒。若要生成更长的视频，请将返回的 interactionId 作为 previousInteractionId 传入；每次续接最多增加 10 秒，并且每次都会返回完整视频片段。
• 提示词中的文字会按原样呈现在屏幕上，包括非拉丁文字，不过 Google 仅将英语列为完全支持的语言。
• 按照 API 文档对于超过 4 MB 文件的建议，视频片段会通过 Google 的文件端点获取，而不是嵌入 JSON 响应中。每次生成预计会额外发送一个请求。
• 720p 输出每秒约需 $0.10；此模型没有免费套餐。

响应

{
  "model": "gemini-omni-1.1-flash",
  "savedFile": "/path/to/1788347054697-491db547.mp4",
  "settings": {
    "durationSeconds": 5,
    "resolution": "720p",
    "aspectRatio": "16:9"
  },
  "interactionId": "v1_...",
  "description": "..."
}

仅当模型在返回视频片段的同时也返回文本时，才会包含 description。

用作库

除了独立的 MCP 服务外，此软件包还可以嵌入其他宿主中—— 例如应用，或希望将图像生成作为自身工具提供的另一个 MCP 服务。

import { createRegistry, generateImageToDisk } from "mcp-imagenate";

// Keys are passed in explicitly; nothing here reads process.env.
const registry = createRegistry({ openai: myOpenAIKey, google: myGoogleKey });

if (registry.models.length === 0) {
  throw new Error("No image provider is configured");
}

const outcome = await generateImageToDisk({
  registry,
  prompt: "a calico cat asleep on a warm keyboard",
  model: registry.defaultModel!,
  aspectRatio: "16:9",
  outputDir: "/somewhere/to/write",
  // outputBaseDir defaults to null, meaning no path sandboxing. Set it to a
  // directory to confine both output and input paths within that directory.
});

console.log(outcome.savedFiles);

generateImageToDisk 接受与工具相同的选项，因此，对于无法提供 alpha 通道的模型，background: "transparent" 会抛出错误。如果模型不是你自行选择的，请先检查 registry.resolve(model).supportsTransparentBackground。

库入口点不会读取 process.env、向 stdio 写入内容，也不会退出进程。若仍要从常规环境变量中读取密钥，请使用 keysFromEnv() 助手。独立服务可通过 mcp-imagenate/server 使用。

导出项	用途
createRegistry(keys)	为给定密钥构建可用模型的注册表
keysFromEnv(env?)	从环境变量中读取提供商密钥
generateImageToDisk(options)	生成图像并写入磁盘
createVideoRegistry(keys)	为给定密钥构建可用视频模型的注册表
generateVideoToDisk(options)	生成片段并写入磁盘
resolveOutputDir / resolveInputImagePath	路径沙箱辅助函数（选择启用）

安全性

• 路径沙箱：设置 NANO_BANANA_OUTPUT_DIR 后，输出路径和输入图像路径都会限制在此目录内。解析到沙箱外部的符号链接会被拒绝。对于库的嵌入方，可通过 outputBaseDir 选择启用，因为宿主通常会控制传入调用的路径。
• 输入验证：输入图像会进行格式（PNG/JPEG/WEBP/GIF）和大小（最大 20 MB）验证。超出模型范围的视频时长会在发送任何请求前被拒绝。
• API 密钥验证：如果未配置 API 密钥，服务会立即退出。库则会将此情况报告为空注册表，由宿主决定如何处理。

许可证

MIT