Which integrations are available for this server?

Provides tools to generate images using Google's Gemini 3 Pro Image model on Vertex AI, supporting reference images, multiple sizes, and GCS uploads.

How do I use nano-banana-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@nano-banana-mcp Generate a photorealistic image of a cat sitting on a beach at sunset" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

nano-banana-mcp

Official

by fahmidme

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

nano-banana-mcp

Architecture Diagram

MCP server that generates images with Gemini 3 Pro Image on Vertex AI.

Requirements

Node.js 18+
Vertex AI API enabled in your GCP project
A service account with permission to call Vertex AI

Related MCP server: Open Google Image Generator MCP

Setup

npm install

Create a .env file or export the variables directly:

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

Notes:

GOOGLE_SERVICE_ACCOUNT_JSON is required (JSON string or file path).
VERTEX_PROJECT_ID is optional if the service account JSON includes project_id.
The default model is gemini-3-pro-image-preview (Vertex preview). Override with another model ID if needed.
NANO_BANANA_GCS_BUCKET is required if you want the server to upload local reference images to GCS.
NANO_BANANA_GCS_PREFIX controls the object prefix for uploaded reference images (default: nano-banana/refs).
NANO_BANANA_OUTPUT_GCS_BUCKET controls the GCS bucket for generated images (defaults to NANO_BANANA_GCS_BUCKET).
NANO_BANANA_OUTPUT_GCS_PREFIX controls the object prefix for generated images (default: nano-banana/outputs).
NANO_BANANA_OUTPUT_DIR sets the local save root (defaults to ~/nano-banana-outputs). Relative outputDir values resolve under this path.
NANO_BANANA_PROGRESS_INTERVAL_MS controls how often progress notifications are emitted (ms) to keep long MCP calls alive. Set 0 to disable.
NANO_BANANA_AUTO_TASK_4K runs 4K generations in task mode automatically to avoid client timeouts (set true to enable).
NANO_BANANA_AUTO_TASK_TTL_MS controls how long auto-task results remain available (ms). Set 0 for no expiry.
If you use GCS fileUri references, grant Storage Object Viewer to the Vertex AI service agent for the bucket.
If you use referenceImagePaths, the MCP service account needs Storage Object Creator (or broader) on the bucket.
For generated image uploads, the MCP service account needs Storage Object Creator (or broader) on the output bucket.
If you see a 404 error with global, try a supported region like us-central1 or europe-west4.

Run

npm run dev

If you run via dist/ (e.g. npm start or an MCP config that points to dist/index.js), run npm run build after code changes.

Long-running calls

If your MCP client enforces the 60s default timeout, use progress notifications or task mode.

4K generations can be auto-run in task mode to avoid timeouts. Enable with NANO_BANANA_AUTO_TASK_4K=true if your client supports tasks. If your client does not support MCP tasks, auto-tasking returns a polling task ID via the normal tool response; call nano_banana_get_task to check status and retrieve the final result.

Progress (keeps a single request alive by resetting the timeout):

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,
  }
);

Tasks (returns immediately, then poll/stream the result):

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);
  }
}

Notes:

Task state is stored in memory; tasks are lost when the server restarts.
Task mode still benefits from progress notifications if the client subscribes.

Polling fallback (for clients without MCP task support):

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
);

Notes:

Polling tasks are stored in memory and are cleared on server restart.
Polling tasks expire after NANO_BANANA_AUTO_TASK_TTL_MS (set 0 to disable expiry).
Completed polling responses include structuredContent with outputImageUris, outputImageUrls, and savedPaths when available.
Wait a few seconds between nano_banana_get_task polls to avoid hammering the server.

MCP tool

Tool name: nano_banana_generate_image Tool name: nano_banana_get_task (polling fallback for auto-task 4K requests)

Example arguments:

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

Responses include GCS URIs (and HTTP URLs) for generated images; image bytes are uploaded to GCS to avoid large MCP payloads. Generated images are also saved locally under NANO_BANANA_OUTPUT_DIR (or outputDir).

Optional fields:

referenceImages: array of { "mimeType": "image/png", "data": "<base64>" } (legacy; prefer URIs or local paths)
referenceImageUris: array of { "mimeType": "image/png", "fileUri": "gs://bucket/path.png" }
referenceImagePaths: array of { "path": "/abs/path.png", "mimeType": "image/png" } (uploads to GCS)
responseModalities: ["IMAGE"] or ["TEXT", "IMAGE"]
candidateCount: integer 1-8
imageSize: 1K, 2K, 4K (for models that support it)
model, location, projectId: overrides
gcsBucket: override the GCS bucket for uploads
gcsUploadPrefix: override the GCS object prefix for uploads
outputGcsBucket: override the GCS bucket for generated image uploads
outputGcsPrefix: override the GCS object prefix for generated image uploads
outputDir: directory to save generated images on disk (relative paths resolve under NANO_BANANA_OUTPUT_DIR)
outputFilePrefix: filename prefix used when saving images and naming GCS objects

Example with a GCS reference image:

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

Example uploading a local image and using it as a reference:

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

References

Gemini 3 Pro Image model card: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-pro-image
Gemini image generation docs (model IDs, response format): https://ai.google.dev/gemini-api/docs/image-generation

Available Tools

2 tools

nano_banana_generate_imageA

Generate images with Gemini 3 Pro Image on Vertex AI and upload results to GCS. Prefer referenceImagePaths or referenceImageUris to avoid base64. For 4K imageSize requests, the server may return a polling task (or MCP task when explicitly requested) when auto-task mode is enabled to avoid client timeouts.

ParametersJSON Schema

Name	Required	Description	Default
`model`	No	Override the model ID (default: gemini-3-pro-image-preview).
`prompt`	No	Text prompt for image generation.
`location`	No	Vertex region (default: VERTEX_LOCATION or global).
`gcsBucket`	No	GCS bucket for reference image uploads.
`imageSize`	No	Image size (1K, 2K, 4K) for models that support it (e.g. Gemini 3 Pro Image Preview).
`outputDir`	No	Directory to save generated images on disk (relative paths resolve under NANO_BANANA_OUTPUT_DIR).	/root/nano-banana-outputs
`projectId`	No	Override the GCP project ID (default from env or service account).
`aspectRatio`	No	Aspect ratio like 1:1, 16:9, 4:3. Gemini 2.5 Flash Image supports fixed ratios.
`includeText`	No	Include text parts in the MCP response.
`candidateCount`	No	Number of candidates to request (1-8).
`gcsUploadPrefix`	No	GCS object prefix for uploaded reference images.	nano-banana/refs
`outputGcsBucket`	No	GCS bucket for generated image uploads.
`outputGcsPrefix`	No	GCS object prefix for generated image uploads.	nano-banana/outputs
`referenceImages`	No	Legacy base64-encoded images (prefer referenceImagePaths or referenceImageUris).
`outputFilePrefix`	No	Optional filename prefix used for GCS object names and local files.
`referenceImageUris`	No	Optional GCS image URIs for editing or multi-image prompts.
`responseModalities`	No	Override response modalities.
`referenceImagePaths`	No	Optional local image paths to upload to GCS and use as references.

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the important async polling behavior for 4K requests and GCS uploads, but does not cover auth requirements, rate limits, or the exact nature of the return value (beyond polling task). This is partial but not exhaustive transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each earning its place: the first states the core purpose, the second provides parameter guidance, and the third discloses an edge-case behavioral trait. It is front-loaded and free of padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high complexity (18 parameters, multiple reference input methods, GCS interactions) and no output schema, the description should explain more about return values and workflows. It mentions the polling task for 4K but does not describe what the default return payload looks like or how to sequence with nano_banana_get_task. This leaves gaps, so a score of 3 is appropriate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds value by recommending referenceImagePaths or referenceImageUris over referenceImages (base64) and by explaining the implications of imageSize=4K. These details go beyond the schema field descriptions, helping the agent choose parameters wisely.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Generate images with Gemini 3 Pro Image on Vertex AI and upload results to GCS.' It specifies the action (generate), the resource (Gemini 3 Pro Image on Vertex AI), and the downstream effect (upload to GCS), fully distinguishing it from the sibling tool nano_banana_get_task which retrieves tasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context by advising 'Prefer referenceImagePaths or referenceImageUris to avoid base64' and explaining the async behavior for 4K imageSize requests. It does not explicitly mention when not to use the tool or name alternatives beyond the implicit sibling relationship, but the guidance is actionable and context-rich.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nano_banana_get_taskA

Get status/results for polling tasks returned by nano_banana_generate_image when auto-task is enabled. Wait a few seconds between polls to avoid hammering the server.

ParametersJSON Schema

Name	Required	Description	Default
`taskId`	Yes	Task ID returned by nano_banana_generate_image.

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals that the operation is a read-style 'get' and includes a warning against hammering the server, which is useful. However, it does not explain error behavior, rate limits, or what the response contains beyond 'status/results'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences with the purpose front-loaded and a brief, valuable usage tip. No unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple polling tool with one parameter, the description covers the core purpose and usage context. It lacks explicit return value details, but the low complexity and clear focus mitigate this. It is adequate but not exhaustive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already fully describes the single parameter (taskId) with 100% coverage, so the description adds little beyond reinforcing that the ID comes from the generation tool. This matches the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's verb ('Get') and resource ('status/results') and ties it to a specific source (tasks from nano_banana_generate_image), making its purpose unmistakable. It also distinguishes from the sibling tool by focusing on polling rather than generation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly indicates when to use the tool (when polling tasks with auto-task enabled) and provides a practical tip (wait between polls). It does not explicitly state when not to use it or discuss alternatives, but the sibling relationship is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

2 tool updatesv0.1.0Aug 1, 2026
- First observednano_banana_generate_image
- First observednano_banana_get_task

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored 2026-08-01 21:30 across 2 tools

Disambiguation5/5

The two tools are unambiguously distinct: one generates images, the other retrieves task status for async operations. There is zero overlap in their purposes.

Naming Consistency5/5

Both tools follow the same verb_noun pattern with a shared 'nano_banana_' prefix: 'generate_image' and 'get_task'. This is perfectly consistent and predictable.

Tool Count4/5

With only two tools, the count is minimal but fits the narrow purpose of image generation with async polling. It could feel slightly thin, but the scope is clear and each tool is essential.

Completeness4/5

The surface covers the core workflow of generating images and retrieving results. Minor gaps exist (e.g., no task cancellation or listing), but these are not critical for the primary use case.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

mcp-qwen-imageOAuth
io.github.AceDataCloud
MCP server for Qwen Image 3 AI image generation
AI & Machine Learning Image & Video Processing
1
mcp-veoOAuth
io.github.AceDataCloud
MCP server for Google Veo AI video generation
Multimedia Processing Image & Video Processing Entertainment & Media
23
mcp-wanOAuth
io.github.AceDataCloud
MCP server for Wan AI video generation
AI & Machine Learning Image & Video Processing
21
mcp-seedream-proOAuth
io.github.AceDataCloud
MCP server for ByteDance Seedream AI image generation
Image & Video Processing Multimedia Processing
23

Related MCP Servers

gemini-image-mcp
App Automation Image & Video Processing Content Management Systems
creating-cat
A
license
B
quality
C
maintenance
An MCP server for image generation using the Gemini API.
Updated a year ago (2025-07-22 08:13 UTC)
1
33
2
MIT
Open Google Image Generator
AI & Machine Learning Image & Video Processing
miracorhan
A
license
Not graded
quality
B
maintenance
MCP server that exposes Google Cloud Vertex AI Imagen and Gemini models for image generation, editing, analysis, and transformation via MCP-compatible clients.
Updated 2 months ago (2026-07-01 20:00 UTC)
2
MIT
Gemini Media MCP
AI & Machine Learning Image & Video Processing
CxOAGI
A
license
Not graded
quality
A
maintenance
MCP server for generating images and videos using Google Gemini and VEO models, with support for multiple AI models and credential modes.
Updated a day ago (2026-09-11 06:05 UTC)
1
Apache 2.0
Nano Banana MCP
Image & Video Processing AI & Machine Learning
charlesdove977
A
license
A
quality
D
maintenance
MCP server for Google Gemini image generation with configurable model support, enabling text-to-image generation, image editing, and iterative refinement.
Updated 5 months ago (2026-03-30 16:16 UTC)
6
40
MIT

nano-banana-mcp

Requirements

Setup

Run

Long-running calls

MCP tool

References

Available Tools

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

gemini-image-mcp

Open Google Image Generator

Gemini Media MCP

Nano Banana MCP