Skip to main content
Glama
ion-aluminium

Nano Banana MCP Server (CLIProxyAPI Edition)

by ion-aluminium
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Nano Banana MCP Server (CLIProxyAPI Edition) 🍌

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

Downstream fork of zhongweili/nanobanana-mcp-server: https://github.com/zhongweili/nanobanana-mcp-server
CLIProxyAPI docs: https://help.router-for.me/cn/introduction/what-is-cliproxyapi.html
Updates in this fork: CLIProxyAPI backend support (Gemini-compatible proxy), updated docs/config examples.

⭐ NEW: Gemini 3 Pro Image Support! 🚀

Now featuring Nano Banana Pro - Google's latest and most powerful image generation model:

  • 🏆 Professional 4K Quality: Generate stunning images up to 3840px resolution

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

  • 🧠 Advanced Reasoning: Configurable thinking levels for complex compositions

  • 🎯 Superior Text Rendering: Crystal-clear text in images at high resolution

  • 🎨 Enhanced Understanding: Better context comprehension for complex prompts

Upstream MCP registry listing:

Related MCP server: KOF Nano Banana MCP Server

✨ Features

  • 🎨 Multi-Model AI Image Generation: Intelligent selection between Flash (speed) and Pro (quality) models

  • ⚡ Gemini 2.5 Flash Image: Fast generation (1024px) for rapid prototyping

  • 🏆 Gemini 3 Pro Image: High-quality up to 4K with Google Search grounding

  • 🤖 Smart Model Selection: Automatically chooses optimal model 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. One of the following:

    • Google Gemini API Key - Get one free here

    • CLIProxyAPI running locally (Gemini-compatible proxy)

  2. Python 3.11+ (for development only)

Installation

Option 1: Upstream MCP Registry (Gemini direct only) The upstream package is listed in the Model Context Protocol Registry.

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

Option 2: From Source (this fork, recommended for CLIProxyAPI)

git clone https://github.com/ion-aluminium/nanobanana-mcp-cliproxyapi.git
cd nanobanana-mcp-cliproxyapi
uv sync

Option 3: Install from Git (this fork)

pip install git+https://github.com/ion-aluminium/nanobanana-mcp-cliproxyapi.git

🔧 Configuration

Authentication Methods

Nano Banana supports these authentication options:

  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.

  4. CLIProxyAPI: Set CLIPROXY_BASE_URL to route requests through a local Gemini-compatible proxy (bypasses Google SDK auth).

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=us-central1 (default)

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: CLIProxyAPI (this fork)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "nanobanana": {
      "command": "python3",
      "args": ["-m", "nanobanana_mcp_server.server"],
      "env": {
        "CLIPROXY_BASE_URL": "http://127.0.0.1:8318",
        "CLIPROXY_API_KEY": "sk-your-cli-proxy-key",
        "NANOBANANA_MODEL": "pro",
        "NO_PROXY": "127.0.0.1,localhost"
      }
    }
  }
}

If you are running from source, you can use uv run python -m nanobanana_mcp_server.server and set cwd to your local repository.

Option 2: Upstream PyPI (Gemini direct only)

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

Option 3: Using Vertex AI (ADC) (Upstream only)

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": "us-central1"
      }
    }
  }
}

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": "python3",
  "args": ["-m", "nanobanana_mcp_server.server"],
  "env": {
    "CLIPROXY_BASE_URL": "http://127.0.0.1:8318",
    "CLIPROXY_API_KEY": "sk-your-cli-proxy-key",
    "NANOBANANA_MODEL": "pro",
    "NO_PROXY": "127.0.0.1,localhost"
  }
}

    Upstream PyPI (Gemini direct) uses uvx nanobanana-mcp-server@latest and GEMINI_API_KEY.

Cursor

Add to Cursor's MCP configuration:

{
  "mcpServers": {
    "nanobanana": {
      "command": "python3",
      "args": ["-m", "nanobanana_mcp_server.server"],
      "env": {
        "CLIPROXY_BASE_URL": "http://127.0.0.1:8318",
        "CLIPROXY_API_KEY": "sk-your-cli-proxy-key",
        "NANOBANANA_MODEL": "pro",
        "NO_PROXY": "127.0.0.1,localhost"
      }
    }
  }
}

Upstream PyPI (Gemini direct) uses uvx nanobanana-mcp-server@latest and GEMINI_API_KEY.

Continue.dev (VS Code/JetBrains)

Add to your config.json:

{
  "mcpServers": [
    {
      "name": "nanobanana",
      "command": "python3",
      "args": ["-m", "nanobanana_mcp_server.server"],
      "env": {
        "CLIPROXY_BASE_URL": "http://127.0.0.1:8318",
        "CLIPROXY_API_KEY": "sk-your-cli-proxy-key",
        "NANOBANANA_MODEL": "pro",
        "NO_PROXY": "127.0.0.1,localhost"
      }
    }
  ]
}

Upstream PyPI (Gemini direct) uses uvx nanobanana-mcp-server@latest and GEMINI_API_KEY.

Open WebUI

Configure in Open WebUI settings:

{
  "mcp_servers": {
    "nanobanana": {
      "command": ["python3", "-m", "nanobanana_mcp_server.server"],
      "env": {
        "CLIPROXY_BASE_URL": "http://127.0.0.1:8318",
        "CLIPROXY_API_KEY": "sk-your-cli-proxy-key",
        "NANOBANANA_MODEL": "pro",
        "NO_PROXY": "127.0.0.1,localhost"
      }
    }
  }
}

Upstream PyPI (Gemini direct) uses ["uvx", "nanobanana-mcp-server@latest"] and GEMINI_API_KEY.

Gemini CLI / Generic MCP Client

# CLIProxyAPI (this fork)
export CLIPROXY_BASE_URL="http://127.0.0.1:8318"
export CLIPROXY_API_KEY="sk-your-cli-proxy-key"
export NANOBANANA_MODEL="pro"
export NO_PROXY="127.0.0.1,localhost"
python3 -m nanobanana_mcp_server.server

# Upstream PyPI (Gemini direct)
export GEMINI_API_KEY="your-gemini-api-key-here"
uvx nanobanana-mcp-server@latest

CLIProxyAPI Mode (Gemini-Compatible Proxy) ⭐ NEW

Set the following environment variables and run as usual:

export CLIPROXY_BASE_URL="http://127.0.0.1:8318"
export CLIPROXY_API_KEY="sk-your-cli-proxy-key"
export NANOBANANA_MODEL="pro"
export NO_PROXY="127.0.0.1,localhost"

uv run python -m nanobanana_mcp_server.server

See the full guide in docs/CLIPROXYAPI.md.

🤖 Model Selection

Nano Banana supports two Gemini models with intelligent automatic selection:

🏆 Pro Model - Nano Banana Pro (Gemini 3 Pro Image) ⭐ NEW!

Google's latest and most advanced image generation model

  • Quality: Professional-grade, production-ready

  • Resolution: Up to 4K (3840px) - highest available

  • Speed: ~5-8 seconds per image

  • Special Features:

    • 🌐 Google Search Grounding: Leverages real-world knowledge for accurate, contextual images

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

    • 📐 Media Resolution Control: Fine-tune vision processing detail (LOW/MEDIUM/HIGH/AUTO)

    • 📝 Superior Text Rendering: Exceptional clarity for text-in-image generation

    • 🎨 Enhanced Context Understanding: Better interpretation of complex, narrative prompts

  • Best for: Production assets, marketing materials, professional photography, high-fidelity outputs, images requiring text, factual accuracy

  • Cost: Higher per image (premium quality)

⚡ Flash Model (Gemini 2.5 Flash Image)

Fast, reliable model for rapid iteration

  • Speed: Very fast (2-3 seconds)

  • Resolution: Up to 1024px

  • Quality: High quality for everyday use

  • Best for: Rapid prototyping, iterations, high-volume generation, drafts, sketches

  • Cost: Lower per image

🤖 Automatic Selection (Recommended)

By default, the server uses AUTO mode which intelligently analyzes your prompt and requirements:

Pro Model Selected When:

  • Quality keywords detected: "4K", "professional", "production", "high-res", "HD"

  • High resolution requested: resolution="4k" or resolution="high"

  • Google Search grounding enabled: enable_grounding=True

  • High thinking level requested: thinking_level="HIGH"

  • Multi-image conditioning with multiple input images

Flash Model Selected When:

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

  • High-volume batch generation: n > 2

  • Standard or lower resolution requested

  • No special Pro features required

Usage Examples

# Automatic selection (recommended)
"Generate a professional 4K product photo"  # → Pro model (quality keywords + 4K)
"Quick sketch of a cat"                     # → Flash model (speed keyword)
"Create a diagram with clear text labels"   # → Pro model (text rendering)
"Draft mockup for website hero section"     # → Flash model (draft keyword)

# Explicit model selection
generate_image(
    prompt="A scenic landscape",
    model_tier="flash"  # Force Flash model for speed
)

# Leverage Nano Banana Pro features
generate_image(
    prompt="Professional product photo of vintage camera on wooden desk",
    model_tier="pro",              # Use Pro model
    resolution="4k",               # 4K resolution (Pro-only)
    thinking_level="HIGH",         # Enhanced reasoning
    enable_grounding=True,         # Use Google Search for accuracy
    media_resolution="HIGH"        # High-detail vision processing
)

# Pro model for high-quality text rendering
generate_image(
    prompt="Infographic showing 2024 market statistics with clear labels",
    model_tier="pro",              # Pro excels at text rendering
    resolution="4k"                # Maximum clarity for text
)

# 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 ⭐ NEW!

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

⚙️ 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=us-central1

# Method 3: CLIProxyAPI (local OAuth/proxy)
# When CLIPROXY_BASE_URL is set, the server uses CLIProxyAPI instead of Google SDK.
CLIPROXY_BASE_URL=http://127.0.0.1:8318
# Provide API key directly or point to CLIProxyAPI config.yaml
CLIPROXY_API_KEY=sk-your-cli-proxy-key
# or:
CLIPROXY_CONFIG=/root/cliproxyapi/config.yaml

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

# Optional
IMAGE_OUTPUT_DIR=/path/to/image/directory  # Default: ~/nanobanana-images
LOG_LEVEL=INFO                             # DEBUG, INFO, WARNING, ERROR
LOG_FORMAT=standard                        # standard, json, detailed

CLIProxyAPI mode notes

  • Uses CLIProxyAPI's Gemini-compatible /v1beta/models/{model}:generateContent.

  • Gemini Files API features are not available (file_id upload / retrieval disabled).

  • Local file editing (input_image_path_*) still works.

🐛 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/ion-aluminium/nanobanana-mcp-cliproxyapi.git
cd nanobanana-mcp-cliproxyapi

# 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
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' (speed, 1024px), 'pro' (quality, up to 4K), or 'auto' (smart selection). Default: 'auto' - automatically selects based on prompt quality/speed indicators.auto
resolutionNoOutput resolution: 'high', '4k', '2k', '1k'. 4K and 2K only available with 'pro' model. Default: 'high'.high
thinking_levelNoReasoning depth for Pro model: 'low' (faster), 'high' (better quality). Only applies to Pro model. Default: 'high'.high
enable_groundingNoEnable Google Search grounding for factual accuracy (Pro model only). Useful for real-world subjects. Default: true.
aspect_ratioNoOptional 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.

TDQS

A4.4/5.0
Behavior4/5

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

The description adds significant behavioral context beyond the annotations. While annotations indicate read-only and open-world hints, the description explains the tool's multi-model behavior (Flash & Pro), automatic mode detection, local filesystem reading to avoid token usage, and dual return format (MCP image blocks + JSON metadata). No contradiction with annotations exists.

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 perfectly structured and front-loaded with the core purpose, followed by numbered usage modes and important behavioral notes. Every sentence adds value with zero waste, making it easy to scan while providing comprehensive information in minimal space.

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 complex 14-parameter tool with no output schema, the description provides excellent context about usage modes, behavioral characteristics, and return formats. It covers the multi-model aspect, automatic detection logic, and practical implementation details. The only minor gap is not explicitly mentioning sibling tool relationships.

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?

With 100% schema description coverage, the schema already documents all 14 parameters thoroughly. The description adds some context about parameter interactions (e.g., automatic mode detection based on parameters) and practical usage notes, but doesn't provide substantial additional semantic information beyond what's in the schema descriptions.

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

Purpose5/5

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

The description clearly states the tool's purpose with specific verbs ('generate new images or edit existing images') and distinguishes it from siblings by specifying it uses natural language instructions and multiple input modes. It goes beyond the title by detailing the dual functionality and multi-model support.

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

Usage Guidelines5/5

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

The description explicitly lists four distinct usage modes (pure generation, multi-image conditioning, File ID editing, file path editing) with clear guidance on when to use each based on parameter combinations. It also explains automatic mode detection and provides practical advice about local filesystem usage to avoid token issues.

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

B3.4/5.0
Behavior2/5

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

The description states the tool performs maintenance operations (including destructive actions like cleanup), but annotations include readOnlyHint=true, creating a contradiction. The tool's mutability is not clarified, and the reference to workflows.md patterns is vague.

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 concise, with a clear opening sentence and a bullet list of operations. It front-loads the purpose and avoids unnecessary words.

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?

The tool has no output schema, and the description does not explain what the tool returns (e.g., reports, status messages). It also omits details about error handling or sequencing of full_cleanup.

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 provides detailed descriptions for all parameters. The description adds the operation list but does not provide additional meaning beyond what the schema offers.

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 performs maintenance operations and lists specific operations like cleanup_expired, check_quota, etc. It distinguishes itself from siblings (generate_image, show_output_stats, upload_file) by focusing on maintenance tasks.

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?

While the description mentions following workflows.md patterns, it does not explicitly state when to use this tool versus alternatives. The operations are self-explanatory, but there is no guidance on exclusions or conditions for use.

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 (readOnlyHint=false, openWorldHint=true) already indicate a mutating, side-effectful operation. The description adds the outcome of returning URI and metadata but lacks details on permissions, error handling, or specific behavioral traits beyond what annotations provide.

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

Conciseness5/5

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

The description is two sentences long, front-loaded with the core purpose, and the second sentence adds a valuable usage hint. Every sentence is purposeful and there is no unnecessary information.

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?

Given no output schema, the description adequately states the return type (URI and metadata). It covers the tool's purpose and usage context. Minor gaps exist regarding file type restrictions or error handling, but overall it is fairly complete for a simple upload tool.

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

Parameters3/5

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

The input schema has 100% parameter description coverage, so the baseline is 3. The description does not add meaning beyond what the schema provides; the mention of 'image' in the usage hint slightly conflicts with the general 'file path' parameter, but not severely.

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 verb 'upload', the resource 'local file through the Gemini Files API', and the outcome 'return its URI & metadata'. It effectively distinguishes from sibling tools like generate_image and maintenance, which have different purposes.

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 a specific use case: 'Useful when the image is larger than 20MB or reused across prompts.' This gives clear context for when to use the tool, though it does not explicitly state when not to use it or provide alternative tools.

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

Scored across 4 tools

Disambiguation5/5

Each tool has a distinct, non-overlapping purpose: generate_image for image creation/editing, maintenance for system cleanup tasks, show_output_stats for statistics viewing, and upload_file for file uploading. There is no ambiguity in their functions, and an agent can easily select the correct tool based on the task.

Naming Consistency3/5

The naming is mixed, with generate_image and upload_file using a verb_noun pattern, while maintenance and show_output_stats are more noun-based or descriptive. This inconsistency makes the pattern less predictable, though the names are still readable and clear in intent.

Tool Count4/5

With 4 tools, the count is reasonable for a server focused on image generation and file management. It covers core operations without being overly sparse or bloated, though it might benefit from a few more specialized tools for advanced image editing or configuration.

Completeness4/5

The tool set covers key workflows: image generation/editing, system maintenance, statistics viewing, and file uploading. Minor gaps exist, such as tools for deleting uploaded files or managing image metadata more directly, but agents can likely work around these with the provided tools.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Imagen MCP Server

    vipincr
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI assistants to generate high-quality images using Google's Gemini and Imagen models with support for multiple aspect ratios, dynamic model selection, and direct file saving capabilities.
    MIT

  • Nano Banana

    saroby
    A
    license
    B
    quality
    D
    maintenance
    Enables image generation using Google Gemini models like Gemini 2.0 Flash and Imagen 3.0 with support for custom aspect ratios and negative prompts. It also allows users to list and manage generated images stored in local directories.
    2
    10 npm
    MIT

  • Nano Banana MCP

    brandon695
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables image generation and editing using Google's Gemini models with support for model selection and custom aspect ratios. Users can generate high-quality images or modify existing ones through natural language prompts while controlling specific parameters like quality and dimensions.
    -