使用说明

纳米香蕉mcp

MCP服务器，在Vertex AI上使用Gemini 3 Pro Image生成图像。

需求

Node.js 18+
在GCP项目中启用Vertex AI API
有权调用Vertex AI的服务帐户

设置

npm install

创建 .env 直接归档或导出变量：

export GOOGLE_SERVICE_ACCOUNT_JSON='{"type":"service_account","project_id":"your-project","private_key":"...","client_email":"..."}'
# or point to a JSON file
export GOOGLE_SERVICE_ACCOUNT_JSON=/absolute/path/to/service-account.json

export VERTEX_PROJECT_ID=your-project
export VERTEX_LOCATION=global
export NANO_BANANA_MODEL=gemini-3-pro-image-preview
export NANO_BANANA_GCS_BUCKET=your-reference-bucket
export NANO_BANANA_GCS_PREFIX=nano-banana/refs
export NANO_BANANA_OUTPUT_GCS_BUCKET=your-output-bucket
export NANO_BANANA_OUTPUT_GCS_PREFIX=nano-banana/outputs
export NANO_BANANA_OUTPUT_DIR=~/nano-banana-outputs
export NANO_BANANA_PROGRESS_INTERVAL_MS=20000
export NANO_BANANA_AUTO_TASK_4K=false
export NANO_BANANA_AUTO_TASK_TTL_MS=1200000

笔记：

GOOGLE_SERVICE_ACCOUNT_JSON 是必需的（JSON字符串或文件路径）。
VERTEX_PROJECT_ID 如果服务帐户JSON包含 project_id.
默认模型为 gemini-3-pro-image-preview （顶点预览）。如果需要，用另一个型号ID覆盖。
NANO_BANANA_GCS_BUCKET 如果您希望服务器将本地参考图像上传到GCS，则需要此选项。
NANO_BANANA_GCS_PREFIX 控制上传的参考图像的对象前缀（默认值： nano-banana/refs).
NANO_BANANA_OUTPUT_GCS_BUCKET 控制生成图像的GCS存储桶（默认为 NANO_BANANA_GCS_BUCKET).
NANO_BANANA_OUTPUT_GCS_PREFIX 控制生成图像的对象前缀（默认值： nano-banana/outputs).
NANO_BANANA_OUTPUT_DIR 设置本地保存根目录（默认为 ~/nano-banana-outputs).相对的 outputDir 值在此路径下解析。
NANO_BANANA_PROGRESS_INTERVAL_MS 控制发出进度通知的频率（ms），以保持长MCP呼叫的有效性。集 0 禁用。
NANO_BANANA_AUTO_TASK_4K 在任务模式下自动运行4K代，以避免客户端超时（设置 true 启用）。
NANO_BANANA_AUTO_TASK_TTL_MS 控制自动任务结果保持可用的时间（毫秒）。集 0 没有过期。
如果您使用GCS fileUri 推荐信、授权书 Storage Object Viewer 到桶的Vertex AI服务代理。
如果你使用 referenceImagePaths，MCP服务帐户需要 Storage Object Creator （或更宽）在桶上。
对于生成的图像上传，MCP服务帐户需要 Storage Object Creator （或更宽）在输出桶上。
如果你看到404错误 global，尝试支持的区域，如 us-central1 或 europe-west4.

跑

npm run dev

如果你跑过 dist/ （例如。 npm start 或指向以下内容的MCP配置 dist/index.js)，跑 npm run build 代码更改后。

长时间通话

如果您的MCP客户端强制执行60秒的默认超时，请使用进度通知或任务模式。

4K代可以在任务模式下自动运行，以避免超时。启用 NANO_BANANA_AUTO_TASK_4K=true 如果你的客户支持任务。如果您的客户端不支持MCP任务，自动任务处理将通过正常的工具响应返回轮询任务ID；呼叫 nano_banana_get_task 检查状态并检索最终结果。

进度（通过重置超时使单个请求保持活动状态）：

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";

const client = new Client(
  { name: "example-client", version: "0.1.0" },
  { capabilities: {} }
);

await client.connect(
  new StdioClientTransport({ command: "nano-banana-mcp" })
);

const result = await client.request(
  {
    method: "tools/call",
    params: {
      name: "nano_banana_generate_image",
      arguments: {
        prompt: "A cinematic landscape at golden hour",
        aspectRatio: "16:9",
      },
    },
  },
  CallToolResultSchema,
  {
    onprogress: (progress) => {
      console.log(progress.message ?? progress.progress);
    },
    resetTimeoutOnProgress: true,
  }
);

任务（立即返回，然后轮询/流式传输结果）：

const stream = client.experimental.tasks.callToolStream(
  {
    name: "nano_banana_generate_image",
    arguments: {
      prompt: "A cinematic landscape at golden hour",
      aspectRatio: "16:9",
    },
  },
  CallToolResultSchema,
  {
    task: {
      ttl: 15 * 60 * 1000,
      pollInterval: 1000,
    },
  }
);

for await (const message of stream) {
  if (message.type === "taskStatus") {
    console.log(message.task.status, message.task.statusMessage ?? "");
  }
  if (message.type === "result") {
    console.log(message.result);
  }
}

笔记：

任务状态存储在内存中；服务器重新启动时，任务丢失。
如果客户端订阅，任务模式仍然受益于进度通知。

轮询回退（适用于没有MCP任务支持的客户端）：

const start = await client.request(
  {
    method: "tools/call",
    params: {
      name: "nano_banana_generate_image",
      arguments: {
        prompt: "A cinematic landscape at golden hour",
        imageSize: "4K",
        aspectRatio: "16:9",
      },
    },
  },
  CallToolResultSchema
);

// extract taskId from start.structuredContent or the text response
const poll = await client.request(
  {
    method: "tools/call",
    params: {
      name: "nano_banana_get_task",
      arguments: { taskId: "<taskId>" },
    },
  },
  CallToolResultSchema
);

笔记：

轮询任务存储在内存中，并在服务器重新启动时清除。
轮询任务在以下时间过期 NANO_BANANA_AUTO_TASK_TTL_MS （套 0 禁用过期）。
已完成的投票回复包括 structuredContent 和 outputImageUris, outputImageUrls，以及 savedPaths 如果可用。
等待几秒钟 nano_banana_get_task 轮询以避免对服务器造成冲击。

MCP工具

工具名称： nano_banana_generate_image 工具名称： nano_banana_get_task （自动任务4K请求的轮询回退）

示例参数：

{
  "prompt": "A cozy ramen shop on a rainy night, cinematic lighting",
  "aspectRatio": "16:9",
  "includeText": false
}

响应包括生成图像的GCS URI（和HTTP URL）；图像字节被上传到地面军事系统，以避免大型MCP有效载荷。生成的图像也保存在本地 NANO_BANANA_OUTPUT_DIR （或 outputDir).

可选字段：

referenceImages：数组 { "mimeType": "image/png", "data": "<base64>" } （传统；首选URI或本地路径）
referenceImageUris：数组 { "mimeType": "image/png", "fileUri": "gs://bucket/path.png" }
referenceImagePaths：数组 { "path": "/abs/path.png", "mimeType": "image/png" } （上传至地面军事系统）
responseModalities: ["IMAGE"] 或 ["TEXT", "IMAGE"]
candidateCount：整数1-8
imageSize: 1K, 2K, 4K （适用于支持它的型号）
model, location, projectId：覆盖
gcsBucket：覆盖GCS存储桶进行上传
gcsUploadPrefix：覆盖上传的GCS对象前缀
outputGcsBucket：覆盖GCS存储桶以进行生成的图像上传
outputGcsPrefix：覆盖生成的图像上传的GCS对象前缀
outputDir：将生成的图像保存在磁盘上的目录（相对路径在下解析 NANO_BANANA_OUTPUT_DIR)
outputFilePrefix：保存图像和命名地面军事系统对象时使用的文件名前缀

GCS参考图像示例：

{
  "prompt": "Use the reference image for style, generate a new scene.",
  "referenceImageUris": [
    {
      "mimeType": "image/png",
      "fileUri": "gs://my-bucket/reference.png"
    }
  ]
}

上传本地图像并将其用作参考的示例：

{
  "prompt": "Transform this into an isometric game scene.",
  "referenceImagePaths": [
    {
      "path": "/absolute/path/to/reference.jpg"
    }
  ]
}

参考文献

Gemini 3 Pro Image型号卡：https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-pro-image
Gemini图像生成文档（型号ID、响应格式）：https://ai.google.dev/gemini-api/docs/image-generation

使用说明

纳米香蕉mcp

需求

设置

跑

长时间通话

MCP工具

参考文献

相关 MCP

多模态生成API服务

图像生成服务

Hugging Face MCP服务器

LLM增强工具包

Heroku平台MCP服务器

图像生成服务器