nanobanana-mcp-server

Generate or edit images (Multi-Model: Flash & Pro)

generate_image

Read-only

Generate new images or edit existing images using natural language instructions, with support for multiple input images and local file editing.

Instructions

Generate new images or edit existing images using natural language instructions.

Supports multiple input modes:

Pure generation: Just provide a prompt to create new images
Multi-image conditioning: Provide up to 3 input images using input_image_path_1/2/3 parameters
File ID editing: Edit previously uploaded images using Files API ID
File path editing: Edit local images by providing single input image path

Automatically detects mode based on parameters or can be explicitly controlled. Input images are read from the local filesystem to avoid massive token usage. Returns both MCP image content blocks and structured JSON with metadata.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`n`	No	Requested image count (model may return fewer).
`mode`	No	Operation mode: 'generate' for new image creation, 'edit' for modifying existing images. Auto-detected based on input parameters if not specified.	auto
`prompt`	Yes	Clear, detailed image prompt. Include subject, composition, action, location, style, and any text to render. Use the aspect_ratio parameter to pin a specific canvas shape when needed.
`file_id`	No	Files API file ID to use as input/edit source (e.g., 'files/abc123'). If provided, this takes precedence over input_image_path_* parameters for the primary input.
`model_tier`	No	Model tier: 'flash' (legacy, 1024px), 'nb2' (4K at Flash speed, default), 'pro' (max quality, 4K), or 'auto' (smart selection). Default: 'auto' - automatically selects nb2 or pro based on prompt.	auto
`resolution`	No	Output resolution: 'high', '4k', '2k', '1k'. 4K and 2K available with 'nb2' and 'pro' models. Default: 'high'.	high
`output_path`	No	Output path for generated image(s). If a file path with extension (e.g., '/path/image.png'), saves directly to that path. If a directory path (e.g., '/path/to/dir/'), uses default filename in that directory. If None, uses IMAGE_OUTPUT_DIR environment variable or ~/nanobanana-images.
`aspect_ratio`	No	Optional output aspect ratio (e.g., '16:9'). Standard: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9. Extreme (nb2 only): 4:1, 1:4, 8:1, 1:8.
`thinking_level`	No	Reasoning depth hint: 'low' (faster), 'high' (better quality). Applied to the 'nb2' model; 'high' also biases auto-selection toward Pro. Default: None (auto).
`negative_prompt`	No	Things to avoid (style, objects, text).
`enable_grounding`	No	Enable Google Search grounding for factual accuracy (NB2 and Pro models). Useful for real-world subjects. Default: true.
`return_full_image`	No	Return full-resolution images in MCP response instead of thumbnails. Warning: full images can be large (3-7MB each for 4K). Default: uses RETURN_FULL_IMAGE env var, or false if not set.
`input_image_path_1`	No	Path to the first input image (png, jpg, jpeg, webp, or gif).
`input_image_path_2`	No	Path to the second input image (png, jpg, jpeg, webp, or gif).
`input_image_path_3`	No	Path to the third input image (png, jpg, jpeg, webp, or gif).
`system_instruction`	No	Optional system tone/style guidance.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.4.6Oct 1, 2026

changedInput schema / properties / input_image_path_1 / description

Previous value: -"Path to first input image for composition/conditioning"New value: +"Path to the first input image (png, jpg, jpeg, webp, or gif)."

changedInput schema / properties / input_image_path_2 / description

Previous value: -"Path to second input image for composition/conditioning"New value: +"Path to the second input image (png, jpg, jpeg, webp, or gif)."

changedInput schema / properties / input_image_path_3 / description

Previous value: -"Path to third input image for composition/conditioning"New value: +"Path to the third input image (png, jpg, jpeg, webp, or gif)."

Changed23 schema fields changedv0.4.0May 1, 2026

changedInput schema / properties / aspect_ratio / anyOf

Previous value: -[
-  {
-    "enum": [
-      "1:1",
-      "2:3",
-      "3:2",
-      "3:4",
-      "4:3",
-      "4:5",
-      "5:4",
-      "9:16",
-      "16:9",
-      "21:9"
-    ],
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "enum": [
+      "1:1",
+      "2:3",
+      "3:2",
+      "3:4",
+      "4:3",
+      "4:5",
+      "5:4",
+      "9:16",
+      "16:9",
+      "21:9",
+      "4:1",
+      "1:4",
+      "8:1",
+      "1:8"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / aspect_ratio / description

Previous value: -"Optional output aspect ratio (e.g., '16:9'). See docs for supported values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9."New value: +"Optional output aspect ratio (e.g., '16:9'). Standard: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9. Extreme (nb2 only): 4:1, 1:4, 8:1, 1:8."

removedInput schema / properties / aspect_ratio / title
```
Removed value: -"Aspect Ratio"
```

changedInput schema / properties / enable_grounding / description

Previous value: -"Enable Google Search grounding for factual accuracy (Pro model only). Useful for real-world subjects. Default: true."New value: +"Enable Google Search grounding for factual accuracy (NB2 and Pro models). Useful for real-world subjects. Default: true."

removedInput schema / properties / enable_grounding / title
```
Removed value: -"Enable Grounding"
```
removedInput schema / properties / file_id / title
```
Removed value: -"File Id"
```
removedInput schema / properties / input_image_path_1 / title
```
Removed value: -"Input Image Path 1"
```
removedInput schema / properties / input_image_path_2 / title
```
Removed value: -"Input Image Path 2"
```
removedInput schema / properties / input_image_path_3 / title
```
Removed value: -"Input Image Path 3"
```
removedInput schema / properties / mode / title
```
Removed value: -"Mode"
```

changedInput schema / properties / model_tier / description

Previous value: -"Model tier: 'flash' (speed, 1024px), 'pro' (quality, up to 4K), or 'auto' (smart selection). Default: 'auto' - automatically selects based on prompt quality/speed indicators."New value: +"Model tier: 'flash' (legacy, 1024px), 'nb2' (4K at Flash speed, default), 'pro' (max quality, 4K), or 'auto' (smart selection). Default: 'auto' - automatically selects nb2 or pro based on prompt."

removedInput schema / properties / model_tier / title
```
Removed value: -"Model Tier"
```
removedInput schema / properties / n / title
```
Removed value: -"N"
```
removedInput schema / properties / negative_prompt / title
```
Removed value: -"Negative Prompt"
```

addedInput schema / properties / output_path

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Output path for generated image(s). If a file path with extension (e.g., '/path/image.png'), saves directly to that path. If a directory path (e.g., '/path/to/dir/'), uses default filename in that directory. If None, uses IMAGE_OUTPUT_DIR environment variable or ~/nanobanana-images."
+}

removedInput schema / properties / prompt / title
```
Removed value: -"Prompt"
```

changedInput schema / properties / resolution / description

Previous value: -"Output resolution: 'high', '4k', '2k', '1k'. 4K and 2K only available with 'pro' model. Default: 'high'."New value: +"Output resolution: 'high', '4k', '2k', '1k'. 4K and 2K available with 'nb2' and 'pro' models. Default: 'high'."

removedInput schema / properties / resolution / title
```
Removed value: -"Resolution"
```

addedInput schema / properties / return_full_image

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Return full-resolution images in MCP response instead of thumbnails. Warning: full images can be large (3-7MB each for 4K). Default: uses RETURN_FULL_IMAGE env var, or false if not set."
+}

removedInput schema / properties / system_instruction / title
```
Removed value: -"System Instruction"
```
changedInput schema / properties / thinking_level / default
```
Previous value: -"high"New value: +null
```

changedInput schema / properties / thinking_level / description

Previous value: -"Reasoning depth for Pro model: 'low' (faster), 'high' (better quality). Only applies to Pro model. Default: 'high'."New value: +"Reasoning depth hint: 'low' (faster), 'high' (better quality). Applied to the 'nb2' model; 'high' also biases auto-selection toward Pro. Default: None (auto)."

removedInput schema / properties / thinking_level / title
```
Removed value: -"Thinking Level"
```

Changed6 schema fields changedv1.0.0Jan 3, 2026

addedInput schema / properties / aspect_ratio

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "1:1",
+        "2:3",
+        "3:2",
+        "3:4",
+        "4:3",
+        "4:5",
+        "5:4",
+        "9:16",
+        "16:9",
+        "21:9"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional output aspect ratio (e.g., '16:9'). See docs for supported values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9.",
+  "title": "Aspect Ratio"
+}

addedInput schema / properties / enable_grounding

Added value: +{
+  "default": true,
+  "description": "Enable Google Search grounding for factual accuracy (Pro model only). Useful for real-world subjects. Default: true.",
+  "title": "Enable Grounding",
+  "type": "boolean"
+}

addedInput schema / properties / model_tier

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": "auto",
+  "description": "Model tier: 'flash' (speed, 1024px), 'pro' (quality, up to 4K), or 'auto' (smart selection). Default: 'auto' - automatically selects based on prompt quality/speed indicators.",
+  "title": "Model Tier"
+}

changedInput schema / properties / prompt / description

Previous value: -"Clear, detailed image prompt. Include subject, composition, action, location, style, and any text to render. Add 'Square image' or '16:9' in the text to influence aspect ratio."New value: +"Clear, detailed image prompt. Include subject, composition, action, location, style, and any text to render. Use the aspect_ratio parameter to pin a specific canvas shape when needed."

addedInput schema / properties / resolution

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": "high",
+  "description": "Output resolution: 'high', '4k', '2k', '1k'. 4K and 2K only available with 'pro' model. Default: 'high'.",
+  "title": "Resolution"
+}

addedInput schema / properties / thinking_level

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": "high",
+  "description": "Reasoning depth for Pro model: 'low' (faster), 'high' (better quality). Only applies to Pro model. Default: 'high'.",
+  "title": "Thinking Level"
+}

First observedSep 24, 2025

TDQS

A4.1/5.0

Behavior4/5

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

Annotations give readOnlyHint=true and openWorldHint=true, so the safety profile is partly covered; the description still adds useful behavior: inputs are read from the local filesystem to avoid token usage, the return payload contains both MCP image content blocks and structured JSON, and mode is auto-detected. It does not mention that images may be persisted to output_path/saved to disk, which sits in mild tension with readOnlyHint, nor does it cover latency or cost.

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

Conciseness4/5

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

Front-loaded with the core capability, then a compact numbered list of input modes and two short bullets on filesystem reading and return format. Slightly verbose for a tool whose schema is fully documented, but every line carries usable information and nothing is buried.

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?

With 16 parameters, 100% schema coverage, and no output schema, the description covers the key decision surface: which mode applies, how inputs are supplied, and what is returned. Coverage would be complete if it stated where artifacts are saved by default and any persistence side effects, which would resolve the readOnlyHint ambiguity.

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?

Schema coverage is 100%, so the baseline is 3; the schema already documents prompt, mode, model_tier, resolution, aspect_ratio, output_path and the input_image_path_* fields. The description reinforces the mode groupings and the up-to-3 image limit but adds little syntax or precedence detail beyond what the schema states (e.g., file_id precedence over input_image_path_*).

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?

States a specific verb+resource ('generate new images or edit existing images using natural language instructions') and enumerates the four operating modes, so the agent can distinguish it from siblings like upload_file and maintenance. Names both the generative and edit capabilities in the same breath.

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?

Explicitly lists the four input modes (pure generation, multi-image conditioning with input_image_path_1/2/3, file_id editing, single local path editing) and says which parameters select each, plus that mode is auto-detected or explicitly controlled. It lacks a 'when not to use this / use X instead' clause, but mode selection guidance is concrete.

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

Deploy Server

Generate or edit images (Multi-Model: Flash & Pro)

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools