Skip to main content
Glama
zhongweili

nanobanana-mcp-server

by zhongweili
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Nano Banana MCP Server 🍌

A production-ready Model Context Protocol (MCP) server that provides AI-powered image generation capabilities through Google's Gemini models with intelligent model selection.

⭐ NEW: Nano Banana 2 — Gemini 3.1 Flash Image! 🍌🚀

Nano Banana 2 (gemini-3.1-flash-image-preview) is now the default model — delivering Pro-level quality at Flash speed:

  • 🍌 Flash Speed + 4K Quality: Up to 3840px at Gemini 2.5 Flash latency

  • 🌐 Google Search Grounding: Real-world knowledge for factually accurate images

  • 🎯 Subject Consistency: Up to 5 characters and 14 objects per scene

  • ✍️ Precision Text Rendering: Crystal-clear text placement in images

  • 🏆 Gemini 3 Pro Image still available for maximum reasoning depth

Related MCP server: Nano-Banana MCP Server

✨ Features

  • 🎨 Multi-Model AI Image Generation: Three Gemini models with intelligent automatic selection

  • 🍌 Gemini 3.1 Flash Image (NB2): Default model — 4K resolution at Flash speed with grounding

  • 🏆 Gemini 3 Pro Image: Maximum reasoning depth for the most complex compositions

  • ⚡ Gemini 2.5 Flash Image: Legacy Flash model for high-volume rapid prototyping

  • 🤖 Smart Model Selection: Automatically routes to NB2 or Pro based on your prompt

  • 📐 Aspect Ratio Control ⭐ NEW: Specify output dimensions (1:1, 16:9, 9:16, 21:9, and more)

  • 📋 Smart Templates: Pre-built prompt templates for photography, design, and editing

  • 📁 File Management: Upload and manage files via Gemini Files API

  • 🔍 Resource Discovery: Browse templates and file metadata through MCP resources

  • 🛡️ Production Ready: Comprehensive error handling, logging, and validation

  • ⚡ High Performance: Optimized architecture with intelligent caching

🚀 Quick Start

Prerequisites

  1. Google Gemini API Key - Get one free here

  2. Python 3.11+ (for development only)

Installation

Option 1: From MCP Registry (Recommended) This server is available in the Model Context Protocol Registry. Search for "nanobanana" or use the MCP name below with your MCP client.

mcp-name: io.github.zhongweili/nanobanana-mcp-server

Option 2: Using uvx

uvx nanobanana-mcp-server@latest

Option 3: Using pip

pip install nanobanana-mcp-server

🔧 Configuration

Authentication Methods

Nano Banana supports two authentication methods via NANOBANANA_AUTH_METHOD:

  1. API Key (api_key): Uses GEMINI_API_KEY. Best for local development and simple deployments.

  2. Vertex AI ADC (vertex_ai): Uses Google Cloud Application Default Credentials. Best for production on Google Cloud (Cloud Run, GKE, GCE).

  3. Automatic (auto): Defaults to API Key if present, otherwise tries Vertex AI.

1. API Key Authentication (Default)

Set GEMINI_API_KEY environment variable.

2. Vertex AI Authentication (Google Cloud)

Required environment variables:

  • NANOBANANA_AUTH_METHOD=vertex_ai (or auto)

  • GCP_PROJECT_ID=your-project-id

  • GCP_REGION=global (default; required for Gemini 3 Pro Image and NB2. Use us-central1 only for the legacy 2.5 Flash Image model.)

Prerequisites:

  • Enable Vertex AI API: gcloud services enable aiplatform.googleapis.com

  • Grant IAM Role: roles/aiplatform.user to the service account.

Claude Desktop

Option 1: Using Published Server (Recommended)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Option 2: Using Local Source (Development)

If you are running from source code, point to your local installation:

{
  "mcpServers": {
    "nanobanana-local": {
      "command": "uv",
      "args": ["run", "python", "-m", "nanobanana_mcp_server.server"],
      "cwd": "/absolute/path/to/nanobanana-mcp-server",
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Option 3: Using Vertex AI (ADC)

To authenticate with Google Cloud Application Default Credentials (instead of an API Key):

{
  "mcpServers": {
    "nanobanana-adc": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "NANOBANANA_AUTH_METHOD": "vertex_ai",
        "GCP_PROJECT_ID": "your-project-id",
        "GCP_REGION": "global"
      }
    }
  }
}

Configuration file locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code (VS Code Extension)

Install and configure in VS Code:

  1. Install the Claude Code extension

  2. Open Command Palette (Cmd/Ctrl + Shift + P)

  3. Run "Claude Code: Add MCP Server"

  4. Configure:

    {
  "name": "nanobanana",
  "command": "uvx",
  "args": ["nanobanana-mcp-server@latest"],
  "env": {
    "GEMINI_API_KEY": "your-gemini-api-key-here"
  }
}

Cursor

Add to Cursor's MCP configuration:

{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.toml (global) or .codex/config.toml (project-scoped):

[mcp_servers.nanobanana]
command = "uvx"
args = ["nanobanana-mcp-server@latest"]

[mcp_servers.nanobanana.env]
GEMINI_API_KEY = "your-gemini-api-key-here"

Or add via the CLI:

codex mcp add

Codex supports both the CLI and VSCode extension using the same config.toml. Once added, Codex can call generate_image, edit_image, and upload_file tools directly in your coding sessions.

Note: The Codex config file is shared by the CLI and the IDE extension. A TOML syntax error will break both simultaneously, so validate your edits carefully.

Continue.dev (VS Code/JetBrains)

Add to your config.json:

{
  "mcpServers": [
    {
      "name": "nanobanana",
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  ]
}

Open WebUI

Configure in Open WebUI settings:

{
  "mcp_servers": {
    "nanobanana": {
      "command": ["uvx", "nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Gemini CLI / Generic MCP Client

# Set environment variable
export GEMINI_API_KEY="your-gemini-api-key-here"

# Run server in stdio mode
uvx nanobanana-mcp-server@latest

# Or with pip installation
python -m nanobanana_mcp_server.server

🤖 Model Selection

Nano Banana supports three Gemini models with intelligent automatic selection:

🍌 NB2 — Nano Banana 2 (Gemini 3.1 Flash Image) ⭐ DEFAULT

Flash speed with Pro-level quality — the best of both worlds

  • Quality: Production-ready 4K output

  • Resolution: Up to 4K (3840px)

  • Speed: ~2-4 seconds per image (Flash-class latency)

  • Special Features:

    • 🌐 Google Search Grounding: Real-world knowledge for factually accurate images

    • 🎯 Subject Consistency: Up to 5 characters and 14 objects per scene

    • ✍️ Precision Text Rendering: Clear, well-placed text in images

  • Best for: Almost everything — production assets, marketing, photography, text overlays

  • model_tier: "nb2" (or "auto" — NB2 is the auto default)

🏆 Pro Model — Nano Banana Pro (Gemini 3 Pro Image)

Maximum reasoning depth for the most demanding compositions

  • Quality: Highest available

  • Resolution: Up to 4K (3840px)

  • Speed: ~5-8 seconds per image

  • Special Features:

    • 🧠 Advanced Reasoning: Configurable thinking levels (LOW/HIGH)

    • 🌐 Google Search Grounding: Real-world knowledge integration

    • 📐 Media Resolution Control: Fine-tune vision processing detail

  • Best for: Complex narrative scenes, intricate compositions, maximum reasoning required

  • model_tier: "pro"

⚡ Flash Model (Gemini 2.5 Flash Image)

Legacy model for high-volume rapid iteration

  • Speed: Very fast (2-3 seconds)

  • Resolution: Up to 1024px

  • Best for: High-volume generation, quick drafts where 4K is not needed

  • model_tier: "flash"

🤖 Automatic Selection (Recommended)

By default, the server uses AUTO mode which routes to NB2 unless Pro's deeper reasoning is clearly needed:

Pro Model Selected When:

  • Strong quality keywords: "4K", "professional", "production", "high-res", "HD"

  • High thinking level requested: thinking_level="HIGH"

  • Multi-image conditioning with multiple input images

NB2 Model Selected When (default):

  • Standard requests, everyday image generation

  • Speed keywords: "quick", "draft", "sketch", "rapid"

  • High-volume batch generation (n > 2)

Usage Examples

# Automatic selection (recommended) — routes to NB2 by default
"A cat sitting on a windowsill"             # → NB2 (default)
"Quick sketch of a cat"                     # → NB2 (speed keyword, NB2 is fast enough)
"Professional 4K product photo"             # → Pro (strong quality keywords)

# Explicit NB2 selection
generate_image(
    prompt="Product photo on white background",
    model_tier="nb2",              # Nano Banana 2 (Flash speed + 4K)
    resolution="4k",
    enable_grounding=True
)

# Leverage Nano Banana Pro for complex reasoning
generate_image(
    prompt="Cinematic scene: three characters in a tense standoff at dusk",
    model_tier="pro",              # Pro for deep reasoning
    resolution="4k",
    thinking_level="HIGH",         # Enhanced reasoning
    enable_grounding=True
)

# Legacy Flash for high-volume drafts
generate_image(
    prompt="Simple icon",
    model_tier="flash"             # Fast 1024px generation
)

# Control aspect ratio for different formats ⭐ NEW!
generate_image(
    prompt="Cinematic landscape at sunset",
    aspect_ratio="21:9"            # Ultra-wide cinematic format
)

generate_image(
    prompt="Instagram post about coffee",
    aspect_ratio="1:1"             # Square format for social media
)

generate_image(
    prompt="YouTube thumbnail design",
    aspect_ratio="16:9"            # Standard video format
)

generate_image(
    prompt="Mobile wallpaper of mountain vista",
    aspect_ratio="9:16"            # Portrait format for phones
)

📐 Aspect Ratio Control

Control the output image dimensions with the aspect_ratio parameter:

Supported Aspect Ratios:

  • 1:1 - Square (Instagram, profile pictures)

  • 4:3 - Classic photo format

  • 3:4 - Portrait orientation

  • 16:9 - Widescreen (YouTube thumbnails, presentations)

  • 9:16 - Mobile portrait (phone wallpapers, stories)

  • 21:9 - Ultra-wide cinematic

  • 2:3, 3:2, 4:5, 5:4 - Various photo formats

# Examples for different use cases
generate_image(
    prompt="Product showcase for e-commerce",
    aspect_ratio="3:4",    # Portrait format, good for product pages
    model_tier="pro"
)

generate_image(
    prompt="Social media banner for Facebook",
    aspect_ratio="16:9"    # Landscape banner format
)

Note: Aspect ratio works with both Flash and Pro models. For best results with specific aspect ratios at high resolution, use the Pro model with resolution="4k".

📁 Output Path Control ⭐ NEW!

Control where generated images are saved with the output_path parameter:

Three modes of operation:

  1. Specific file path - Save to an exact file location:

generate_image(
    prompt="A beautiful sunset",
    output_path="/path/to/sunset.png"  # Exact file location
)

  1. Directory path - Use auto-generated filename in a specific directory:

generate_image(
    prompt="Product photo",
    output_path="/path/to/products/"  # Trailing slash indicates directory
)

  1. Default location - Uses IMAGE_OUTPUT_DIR or ~/nanobanana-images:

generate_image(
    prompt="Random image"
    # output_path defaults to None
)

Multiple images (n > 1): When generating multiple images with a file path, images are automatically numbered:

  • First image: /path/to/image.png

  • Second image: /path/to/image_2.png

  • Third image: /path/to/image_3.png

Precedence Rules:

  1. output_path parameter (if provided) - highest priority

  2. IMAGE_OUTPUT_DIR environment variable

  3. ~/nanobanana-images (default fallback)

IMAGE_OUTPUT_DIR is used only when output_path is omitted. A relative output_path such as images/sunset.png is resolved from the server process working directory, not from IMAGE_OUTPUT_DIR. ~/... expands to the home directory. A trailing slash selects directory mode even when that directory does not exist yet (outputs/), and the server creates it and generates the filename.

# Save to specific location with Pro model
generate_image(
    prompt="Professional headshot",
    model_tier="pro",
    output_path="/Users/me/photos/headshot.png"
)

# Save multiple images to a directory
generate_image(
    prompt="Product variations",
    n=4,
    output_path="/path/to/products/"  # Each gets unique filename
)

⚙️ Environment Variables

Configuration options:

# Authentication (Required)
# Method 1: API Key
GEMINI_API_KEY=your-gemini-api-key-here

# Method 2: Vertex AI (Google Cloud)
NANOBANANA_AUTH_METHOD=vertex_ai
GCP_PROJECT_ID=your-project-id
GCP_REGION=global  # Required for gemini-3-pro-image-preview and NB2; use "us-central1" only for legacy 2.5 Flash Image

# Model Selection (optional)
NANOBANANA_MODEL=auto  # Options: flash, nb2, pro, auto (default: auto → nb2)

# Optional
IMAGE_OUTPUT_DIR=/path/to/image/directory  # Default: ~/nanobanana-images
GEMINI_BASE_URL=https://custom-api.example.com  # Custom API endpoint (for proxies/gateways)
LOG_LEVEL=INFO                             # DEBUG, INFO, WARNING, ERROR
LOG_FORMAT=standard                        # standard, json, detailed

🐛 Troubleshooting

Common Issues

"GEMINI_API_KEY not set"

  • Add your API key to the MCP server configuration in your client

  • Get a free API key at Google AI Studio

"Server failed to start"

  • Ensure you're using the latest version: uvx nanobanana-mcp-server@latest

  • Check that your client supports MCP (Claude Desktop 0.10.0+)

"Permission denied" errors

  • The server creates images in ~/nanobanana-images by default

  • Ensure write permissions to your home directory

Development Setup

For local development:

# Clone repository
git clone https://github.com/zhongweili/nanobanana-mcp-server.git
cd nanobanana-mcp-server

# Install with uv
uv sync

# Set environment
export GEMINI_API_KEY=your-api-key-here

# Run locally
uv run python -m nanobanana_mcp_server.server

📄 License

MIT License - see LICENSE for details.

🆘 Support

Available Tools

4 tools
generate_imageGenerate or edit images (Multi-Model: Flash & Pro)A
Read-only

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

Supports multiple input modes:

  1. Pure generation: Just provide a prompt to create new images

  2. Multi-image conditioning: Provide up to 3 input images using input_image_path_1/2/3 parameters

  3. File ID editing: Edit previously uploaded images using Files API ID

  4. 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
nNoRequested image count (model may return fewer).
modeNoOperation mode: 'generate' for new image creation, 'edit' for modifying existing images. Auto-detected based on input parameters if not specified.auto
promptYesClear, 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_idNoFiles 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_tierNoModel 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
resolutionNoOutput resolution: 'high', '4k', '2k', '1k'. 4K and 2K available with 'nb2' and 'pro' models. Default: 'high'.high
output_pathNoOutput 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_ratioNoOptional 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_levelNoReasoning depth hint: 'low' (faster), 'high' (better quality). Applied to the 'nb2' model; 'high' also biases auto-selection toward Pro. Default: None (auto).
negative_promptNoThings to avoid (style, objects, text).
enable_groundingNoEnable Google Search grounding for factual accuracy (NB2 and Pro models). Useful for real-world subjects. Default: true.
return_full_imageNoReturn 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_1NoPath to the first input image (png, jpg, jpeg, webp, or gif).
input_image_path_2NoPath to the second input image (png, jpg, jpeg, webp, or gif).
input_image_path_3NoPath to the third input image (png, jpg, jpeg, webp, or gif).
system_instructionNoOptional system tone/style guidance.

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.

maintenanceMaintenance and cleanup operationsB
Read-only

Perform maintenance operations following workflows.md patterns.

Available operations:

  • cleanup_expired: Remove expired Files API entries from database

  • cleanup_local: Clean old local files based on age/LRU

  • check_quota: Check Files API storage usage vs. ~20GB budget

  • database_hygiene: Clean up database inconsistencies

  • full_cleanup: Run all cleanup operations in sequence

ParametersJSON Schema
NameRequiredDescriptionDefault
dry_runNoIf true, only report what would be done without making changes
operationYesMaintenance operation to perform: 'cleanup_expired', 'cleanup_local', 'check_quota', 'database_hygiene', 'full_cleanup'
keep_countNoFor local cleanup: minimum number of recent files to keep
max_age_hoursNoFor local cleanup: maximum age in hours (default: 168 = 1 week)

TDQS

B3.2/5.0
Behavior1/5

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

Annotations declare readOnlyHint=true, but the description explicitly describes destructive actions like 'Remove expired Files API entries from database' and 'Clean old local files'. This is a direct annotation contradiction, which the rubric requires scoring as 1, and the description also fails to disclose irreversibility or safety implications beyond the dry_run parameter in the schema.

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?

The description is compact and front-loaded with a clear purpose, followed by a well-structured bullet list of operations. The phrase 'following workflows.md patterns' is somewhat ambiguous and could be clearer, but overall every line adds useful information without unnecessary verbosity.

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 tool has four parameters, multiple operation modes, and no output schema, the description covers the operation choices reasonably well. However, it relies on a vague external reference, does not describe return values or success/failure behavior, and the readOnlyHint contradiction makes the safety profile incomplete for an agent deciding whether to invoke it.

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 description coverage is 100%, so the input schema already fully documents operation, dry_run, keep_count, and max_age_hours. The description adds a helpful mapping of operation names to behaviors, but does not provide extra parameter semantics beyond what the schema already gives, so it stays at the baseline.

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 names a specific resource ('maintenance operations') and enumerates each concrete sub-operation with a verb and object, such as 'Remove expired Files API entries from database' and 'Check Files API storage usage'. It is clearly distinguishable from sibling tools like generate_image and upload_file, so an agent can tell what this tool does without opening the schema.

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

Usage Guidelines3/5

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

The description implies this tool is for maintenance and cleanup tasks, but it does not explicitly state when to use it versus sibling tools or when to prefer one operation over another. The reference to 'following workflows.md patterns' gives some context but is vague and does not provide concrete selection criteria or exclusions.

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

show_output_statsShow output directory statsA
Read-only

Show statistics about the output directory and recently generated images.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior3/5

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

The annotations already declare readOnlyHint=true, and the description's use of 'Show' is consistent with that. It adds useful scoping around output directory and recently generated images, but it does not disclose output format, potential cost, or hidden scanning behavior. Given the read-only annotation, a mid-range score is appropriate.

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 a single, front-loaded sentence with no filler, repetition, or unnecessary detail. It communicates the verb, resource, and scope efficiently.

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 zero-parameter, read-only stats tool, the description adequately states what the tool operates on and what it returns at a high level. No output schema exists, so 'statistics' is somewhat vague, but the tool is simple enough that an agent can select and invoke it correctly without more detail.

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?

The tool has zero parameters, so there is no parameter behavior to explain. The baseline of 4 applies here because the description does not need to compensate for missing parameter documentation.

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

Purpose4/5

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

The description uses a specific verb ('Show') and clearly identifies the resource ('statistics about the output directory and recently generated images'). It is clearly distinct from generate_image and upload_file, but it does not explicitly differentiate itself from fetch_generation or maintenance.

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

Usage Guidelines3/5

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

The description implies a monitoring use case for checking output directory stats, but it provides no explicit when-to-use guidance or exclusions. Sibling tools like fetch_generation are not referenced as alternatives, so an agent must infer when this tool is appropriate.

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

upload_fileUpload file to Gemini Files APIA

Upload a local file through the Gemini Files API and return its URI & metadata. Useful when the image is larger than 20MB or reused across prompts.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesServer-accessible file path to upload to Gemini Files API.
display_nameNoOptional display name for the uploaded file.

TDQS

A4/5.0
Behavior3/5

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

Annotations indicate it's a write operation (readOnlyHint=false) and returns dynamic data (openWorldHint=true). The description adds return details (URI & metadata) and a usage condition, but doesn't elaborate on side effects or requirements beyond what the schema provides. With annotations present, the burden is partially met.

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 consists of two concise sentences. The first states the exact purpose, and the second adds a valuable usage condition. 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?

The tool has no output schema, so the description partially covers return values (URI and metadata). It addresses large file support, which is a key concern for uploads. Missing details like overwrite behavior or error conditions, but overall sufficient for typical use.

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% with descriptions for both parameters. The description does not add new semantic meaning beyond the schema; it confirms the path is server-accessible and display_name is optional, which is already documented. Baseline of 3 is appropriate.

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 uploads a local file to the Gemini Files API and returns its URI and metadata. It distinguishes itself from siblings like generate_image by focusing on file upload rather than image 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 provides specific context for when to use the tool: when the image is larger than 20MB or reused across prompts. It doesn't explicitly list alternatives or when not to use, but the context is clear and helpful.

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.

  1. 3 tool updatesv0.4.6
    • Changedgenerate_image3 fields changed
      • 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)."
    • Addedmaintenance
    • Addedshow_output_stats
  2. 2 tool updates
    • Removedmaintenance
    • Removedshow_output_stats
  3. 3 tool updatesv0.4.0
    • Changedgenerate_image23 fields changed
      • 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"
    • Changedmaintenance4 fields changed
      • removedInput schema / properties / dry_run / title
        Removed value: -"Dry Run"
      • removedInput schema / properties / keep_count / title
        Removed value: -"Keep Count"
      • removedInput schema / properties / max_age_hours / title
        Removed value: -"Max Age Hours"
      • removedInput schema / properties / operation / title
        Removed value: -"Operation"
    • Changedupload_file2 fields changed
      • removedInput schema / properties / display_name / title
        Removed value: -"Display Name"
      • removedInput schema / properties / path / title
        Removed value: -"Path"
  4. 1 tool updatev1.0.0
    • Changedgenerate_image6 fields changed
      • 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"
+}
  5. 4 tool updates
    • First observedgenerate_image
    • First observedmaintenance
    • First observedshow_output_stats
    • First observedupload_file
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 4 tools

Disambiguation4/5

The four tools have fairly distinct purposes: generate_image for creation/editing, upload_file for file management, show_output_stats for statistics, and maintenance for cleanup operations. There is a minor potential overlap between generate_image's file-based editing modes and upload_file, but the descriptions clarify when to use each.

Naming Consistency4/5

Three tools follow a verb_noun pattern (generate_image, upload_file, show_output_stats), while 'maintenance' is a bare noun. This is a minor deviation, but the overall set remains readable and mostly consistent.

Tool Count5/5

With only four tools, the server covers the core workflow of image generation, file uploading, output inspection, and system maintenance. Each tool clearly earns its place, and the count is well-suited to the server's focused purpose.

Completeness4/5

The toolset covers generation, editing, file upload, stats, and maintenance operations like cleanup and quota checks. Minor gaps include no dedicated tool to list or delete individual generated images, but the maintenance operations can handle cleanup indirectly.

Maintenance

ActivityMaintained
ResponsivenessSlow

Resources

Related MCP Connectors

Related MCP Servers