Skip to main content
Glama
zhongweili

nanobanana-mcp-server

by zhongweili
OverviewSchemaRelated ServersScoreDiscussions
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)

# 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)B
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
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.
nNoRequested image count (model may return fewer).
negative_promptNoThings to avoid (style, objects, text).
system_instructionNoOptional system tone/style guidance.
input_image_path_1NoPath to first input image for composition/conditioning
input_image_path_2NoPath to second input image for composition/conditioning
input_image_path_3NoPath to third input image for composition/conditioning
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.
modeNoOperation mode: 'generate' for new image creation, 'edit' for modifying existing images. Auto-detected based on input parameters if not specified.auto
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
thinking_levelNoReasoning depth hint: 'low' (faster), 'high' (better quality). Applied to the 'nb2' model; 'high' also biases auto-selection toward Pro. Default: None (auto).
enable_groundingNoEnable Google Search grounding for factual accuracy (NB2 and Pro models). Useful for real-world subjects. Default: true.
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.
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.
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.

TDQS

B3.4/5.0
Behavior1/5

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

The description describes write operations ('generate new images or edit existing images'), but annotations set readOnlyHint to true, which indicates the tool should not modify data. This is a direct contradiction. While the description adds useful behavioral details (auto-detection, local filesystem reading, return format), the contradiction severely undermines transparency.

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 relatively long but well-structured with bullet points and clear numbered modes. It front-loads the core purpose. Some redundancy exists (e.g., mode auto-detection mentioned twice), but overall it is efficiently organized.

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 (16 params, multiple modes) and no output schema, the description covers input modes and general behavior but lacks details on output structure, error handling, or performance implications. It mentions returning 'MCP image content blocks and structured JSON' without specifying the JSON format. Completeness is adequate but not thorough.

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 baseline is 3. The description adds context about input modes and mode auto-detection but does not significantly enhance understanding of individual parameters beyond what the schema provides. The description's added value is moderate.

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 'Generate new images or edit existing images using natural language instructions' and lists four specific input modes. The title reinforces the purpose with 'Multi-Model: Flash & Pro'. It is distinct from sibling tools (maintenance, show_output_stats, upload_file).

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 explicitly lists four input modes and explains automatic mode detection based on parameters. It also details the 'mode' parameter with 'generate' and 'edit' options. However, it does not explicitly state when to avoid using this tool or compare it to alternatives; but siblings are unrelated, so context is clear.

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

maintenanceMaintenance and cleanup operationsC
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
operationYesMaintenance operation to perform: 'cleanup_expired', 'cleanup_local', 'check_quota', 'database_hygiene', 'full_cleanup'
dry_runNoIf true, only report what would be done without making changes
max_age_hoursNoFor local cleanup: maximum age in hours (default: 168 = 1 week)
keep_countNoFor local cleanup: minimum number of recent files to keep

TDQS

C2.7/5.0
Behavior1/5

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

Description states operations like 'cleanup_expired' and 'cleanup_local' that remove data, but annotations declare readOnlyHint=true, a contradiction. No mention of destructive nature beyond operation names. Dry-run parameter is not highlighted. Annotation contradiction flag set to true.

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?

Description is short and well-structured with a bullet list for operations. It is front-loaded with a general statement. No superfluous content, but it could be even more concise by avoiding the external reference.

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

Completeness2/5

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

Without an output schema, the description should explain what each operation returns or reports. It does not. The contradiction with annotations is not addressed, and the 'workflows.md' reference is unexplained. The tool has multiple operations with different behaviors, but completeness is lacking.

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 parameters are well-documented in the schema. The description adds minimal additional meaning—only listing operation names and referencing an external file (workflows.md). The schema already explains each operation, so description adds limited value.

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 clearly identifies the tool's purpose: performing maintenance operations with a list of specific tasks. The sibling tools are unrelated (generate_image, show_output_stats, upload_file), so differentiation is clear. However, the description references 'workflows.md patterns' which may not be accessible, slightly reducing clarity.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool vs alternatives or how to choose between operations. Prerequisites and context are missing. The description merely lists operations without explaining appropriate usage scenarios.

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.9/5.0
Behavior3/5

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

Annotations already mark readOnlyHint=true, so the description need not repeat. It adds context about the scope (output directory and recent images) but doesn't elaborate on performance, frequency limits, or specific behaviors.

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 one concise sentence that clearly conveys the tool's purpose without extraneous text.

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?

The tool has no output schema, so the description should hint at what stats are returned. The current description is vague ('statistics', 'recently generated images') and could be improved by listing examples like file count or total size.

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?

There are no parameters, so the description adds nothing beyond the schema. With 100% schema coverage and zero params, the baseline is met; no additional explanation is needed.

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 shows statistics about the output directory and recently generated images. It uses a specific verb 'show' and identifies the resource, distinguishing it from sibling tools like generate_image and upload_file.

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 use for retrieving stats but does not explicitly instruct when to use this tool versus siblings, nor does it provide conditions for use or exclusions.

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. Dates show when Glama detected each change.

  1. 2 tool updates
    • Removedmaintenance
    • Removedshow_output_stats
  2. 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"
  3. 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"
+}
  4. 4 tool updates
    • First observedgenerate_image
    • First observedmaintenance
    • First observedshow_output_stats
    • First observedupload_file
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: generate_image creates/edits images, maintenance handles cleanup, show_output_stats displays statistics, and upload_file uploads files. No overlap in functionality.

Naming Consistency3/5

Names use mixed patterns: verb_noun (generate_image, upload_file), verb_noun_noun (show_output_stats), and a noun (maintenance). While readable, the inconsistency could cause confusion.

Tool Count4/5

4 tools is appropriate for an image generation server, covering core operations. It could benefit from additional tools like delete_image, but the current count is reasonable.

Completeness3/5

The set covers generation, editing, upload, and maintenance, but lacks explicit listing or deletion of images, and show_output_stats is somewhat superficial. Notable gaps exist.

Maintenance

ActivityInactive
ResponsivenessWithin a week

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/zhongweili/nanobanana-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server