Skip to main content
Glama

Nano-Banana MCP Server v2 🍌

An enhanced Model Context Protocol (MCP) server that provides AI image generation and editing capabilities using Google's Gemini Multimodal Image APIs (gemini-3.1-flash-image / gemini-3-pro-image).

This is a v2 fork of the original nano-banana-mcp server, updated to support modern Gemini models, custom model configuration, and direct-from-GitHub installation.


🎨 Sample Output (Imagen 4)

Here is a preview image generated using the generate_imagen tool with the default imagen-4.0-generate-001 model:

For full visual verification and diagnostic logs for this version tag, see the TEST_REPORT.md.


✨ Features

  • 🎨 Generate Images: Create new images from text descriptions.

  • ✏️ Edit Images: Modify existing images using text prompts and optional reference images.

  • πŸ”„ Iterative Editing: Refine the last generated or edited image sequentially.

  • 🧠 Dynamic Model Selection: Specify which model to use via tool parameters, environment variables, or rely on a smart modern fallback.

  • πŸš€ Zero-Publish Install: Install directly from your GitHub repository using standard Git URLs.

  • πŸ“ Cross-Platform Auto-Saving: Automatically saves generated images locally under platform-appropriate directories.


Related MCP server: nano-banana-mcp

πŸ› οΈ Supported Gemini Models

By default, the server uses gemini-3.1-flash-image, which replaces the deprecated gemini-2.5-flash-image-preview.

You can configure or specify:

  • gemini-3.1-flash-image: Standard efficiency model optimized for speed and high-volume generation.

  • gemini-3-pro-image: High-fidelity creative model optimized for highly contextual native image creation.


πŸ”‘ Configuration & Environment Variables

The server checks configuration in the following priority:

  1. Tool Arguments: Pass model explicitly inside tool calls (highest priority).

  2. Environment Variables:

    • GEMINI_API_KEY: Your Gemini developer token from Google AI Studio.

    • GEMINI_IMAGE_MODEL: Set a default model server-wide (e.g., gemini-3-pro-image).

  3. Global Configuration: ~/.nano-banana-config.json generated globally via the configure_gemini_token tool (with fallback/auto-migration for existing local files).


πŸ”„ Upgrading & Key Migration from v1

If you are upgrading from the original nano-banana-mcp v1 server, your key migration is handled seamlessly:

  • Automatic Detection: The v2 server checks the current directory for any existing .nano-banana-config.json files from v1.

  • Global Persistence: If a local key is loaded and no global config exists, it automatically migrates the configuration globally to ~/.nano-banana-config.json.

  • Directory Independence: After running the server once in your old workspace, you can safely delete the local .nano-banana-config.json file and use the tools from any workspace.


πŸ”‘ Getting Your API Key & Google AI Studio Limits

How to Get Your API Key

  1. Go to Google AI Studio.

  2. Click on "Create API Key" at the top left.

  3. Select an existing Google Cloud project or create a new one, and copy your API key.

Rate Limits & Pricing Plans (as of 2026)

  • Paid/Pay-As-You-Go Plan Required: Native image generation and editing using the Gemini 3 image models (gemini-3.1-flash-image and gemini-3-pro-image) are premium capabilities. Google AI Studio generally requires a Pay-As-You-Go plan for image-based generation models; standard free tiers may restrict these capabilities.

  • Token Billing: Image requests are billed on a pay-per-token basis, consuming approximately 1,290 tokens per generated image.

  • Rate Limits: Enforced at the project level. Exceeding your Requests Per Minute (RPM) or Tokens Per Minute (TPM) quotas will result in a 429: Resource Exhausted error. You can monitor and adjust your limits in the Google AI Studio console settings.


πŸš€ Installation & Client Integration

First, compile the Go binary inside the project directory:

go build -o nano-banana-mcpv2 main.go

To verify that your API key is configured correctly and image generation is functional over stdio, you can run the test script:

export GEMINI_API_KEY="your-api-key-here"
./scripts/test_generation.sh

Then add this to your MCP settings file (e.g., Cursor, Claude Desktop, or Claude Code config):

{
  "mcpServers": {
    "nano-banana-mcpv2": {
      "command": "/path/to/nano-banana-mcpv2",
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here",
        "GEMINI_IMAGE_MODEL": "gemini-3.1-flash-image"
      }
    }
  }
}

Method B: Download Pre-compiled Binary

You can download the pre-compiled binary for your system (macOS ARM64/AMD64, Linux AMD64/ARM64, or Windows) directly from the GitHub Releases page.

Once downloaded, make it executable (chmod +x nano-banana-mcpv2) and add it to your path or reference it directly:

{
  "mcpServers": {
    "nano-banana-mcpv2": {
      "command": "/path/to/downloaded/nano-banana-mcpv2",
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Method C: Run via Docker

Build the minimal Docker image:

docker build -t nano-banana-mcpv2 .

Then configure your MCP client to run the server inside the Docker container:

{
  "mcpServers": {
    "nano-banana-mcpv2": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GEMINI_API_KEY=your-gemini-api-key-here",
        "nano-banana-mcpv2"
      ]
    }
  }
}

πŸ”§ Available Tools

generate_image

Create a new image from a text description using Gemini multimodal native generation.

  • prompt (required): Description of the image to generate.

  • model (optional): Custom model name to use for this generation (e.g., gemini-3.1-flash-image).

  • aspectRatio (optional): Aspect ratio for the image (1:1, 16:9, 9:16, 4:3, 3:4). Defaults to 1:1.

generate_imagen

Generate a new high-fidelity image from a text description using Google's dedicated Imagen model (e.g., imagen-4.0-generate-001).

  • prompt (required): Description of the image to generate.

  • model (optional): Dedicated Imagen model version (defaults to imagen-4.0-generate-001).

  • aspectRatio (optional): Aspect ratio for the image (1:1, 16:9, 9:16, 4:3, 3:4). Defaults to 1:1.

  • numberOfImages (optional): Number of images to generate (1 to 4). Defaults to 1.

  • negativePrompt (optional): Description of elements to avoid in the generated image.

edit_image

Modify a specific existing image file.

  • imagePath (required): Full local file path of the base image.

  • prompt (required): Description of modifications.

  • referenceImages (optional): Array of image file paths for style transfer or guidance.

  • model (optional): Custom model name to use.

  • aspectRatio (optional): Aspect ratio for the output image (1:1, 16:9, 9:16, 4:3, 3:4). Defaults to 1:1.

continue_editing

Refine the last image generated/edited in the active session.

  • prompt (required): Description of modification.

  • referenceImages (optional): Array of reference image file paths.

  • model (optional): Custom model name to use.

get_last_image_info

Check details of the last generated/edited image in the active session (file path, file size, last modified timestamp).

get_configuration_status

Verify if the Gemini token is configured and see its origin source.

configure_gemini_token

Configure your Gemini API key:

  • apiKey (required): Your Google AI Studio Gemini API key.


πŸ“ File Storage Directories

Images are saved automatically to:

  • Windows: %USERPROFILE%\Documents\nano-banana-images\

  • macOS/Linux: ./generated_imgs/ (or ~/nano-banana-images/ if run from system directories).


🀝 Contributing & Branches

  • main: Production-ready, stable releases (tagged v*.*.*).

  • dev: Active features, improvements, and pre-releases (tagged v*.*.*-beta.*).

Make sure to commit changes to the dev branch and open a PR to main for release.


πŸ“„ License & Credits

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • Original Project: Forked from the excellent ConechoAI/Nano-Banana-MCP (originally generated by Claude Code).

  • Google AI: For the powerful Gemini Multimodal Image APIs.

  • Anthropic: For the Model Context Protocol (MCP) specification.

Available Tools

6 tools
configure_gemini_tokenA

Configure your Gemini API token for nano-banana image generation

ParametersJSON Schema
NameRequiredDescriptionDefault
apiKeyYesYour Gemini API key from Google AI Studio

TDQS

A3.5/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It merely says 'Configure your Gemini API token' without disclosing whether the token is stored persistently, overwrites existing configurations, or has any side effects. This is a significant gap for a mutation-like tool.

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, clear sentence with no unnecessary words. It is appropriately front-loaded with the verb and object.

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 is simple (1 param, no output schema), and the description states its purpose and domain. However, it lacks behavioral context such as persistence or success/failure indications, which matters given the absence of annotations. It is adequate but has clear gaps.

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

Parameters3/5

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

The schema already provides a description for apiKey ('Your Gemini API key from Google AI Studio'), and the description adds only the term 'token', which is synonymous. With 100% schema coverage, there is no additional meaning added.

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 uses the specific verb 'configure' and identifies the resource 'Gemini API token', clearly distinguishing this from sibling tools like generate_image or get_configuration_status. It also connects to the domain of nano-banana 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 Guidelines3/5

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

The phrase 'for nano-banana image generation' implies this is a prerequisite for generation, but it does not explicitly state when to use it versus alternatives like get_configuration_status, nor does it mention exclusions. The usage is implied rather than explicit.

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

continue_editingA

Continue editing the LAST image that was generated or edited in this session, optionally using additional reference images. Use this for iterative improvements, modifications, or changes to the most recent image. This automatically uses the previous image without needing a file path.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesText describing the modifications/changes/improvements to make to the last image (e.g., 'change the hat color to red', 'remove the background', 'add flowers')
referenceImagesNoOptional array of file paths to additional reference images to use during editing (e.g., for style transfer, adding elements from other images, etc.)
modelNoOptional model name to use for image editing. Defaults to environment variable GEMINI_IMAGE_MODEL, or 'gemini-3.1-flash-image' if unset.

TDQS

A4.1/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses that the tool automatically uses the previous image, which is key. However, it does not describe what happens if no previous image exists, whether the tool modifies session state, or what the output is. For a mutation tool, more behavioral detail is needed.

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: the first defines what the tool does, the second explains its use case. It is clear, front-loaded, and contains no unnecessary words or fluff.

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?

There is no output schema, so the description should explain return values or behavior, but it does not. It also omits error conditions (e.g., no previous image in session). Given the complexity of image editing with optional references, the description is incomplete.

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

Parameters4/5

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds context by explaining the purpose of reference images (style transfer, adding elements) and the automatic use of the previous image, which enhances understanding beyond the schema's 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 continues editing the last image from the session, with optional reference images. It specifies the verb 'continue editing', the resource 'last image', and distinguishes from siblings like edit_image (which likely requires a file path) and generate_image (creates new).

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 says to use for iterative improvements on the most recent image and notes that it automatically uses the previous image without needing a file path. This guides the agent on when to use this tool instead of edit_image or generate_image. However, it does not explicitly state when not to use it or mention alternatives.

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

edit_imageA

Edit a SPECIFIC existing image file, optionally using additional reference images. Use this when you have the exact file path of an image to modify.

ParametersJSON Schema
NameRequiredDescriptionDefault
imagePathYesFull file path to the main image file to edit
promptYesText describing the modifications to make to the existing image
referenceImagesNoOptional array of file paths to additional reference images to use during editing (e.g., for style transfer, adding elements, etc.)
modelNoOptional model name to use for image editing. Defaults to environment variable GEMINI_IMAGE_MODEL, or 'gemini-3.1-flash-image' if unset.

TDQS

A3.7/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention whether editing overwrites the original file, creates a new file, or what side effects (e.g., destructive changes) occur. This lack of transparency is a significant gap for a mutation tool.

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 very concise at two sentences, with the key action and usage context front-loaded. No wasted words.

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 there is no output schema and no annotations, the description is somewhat incomplete. It does not describe the return value, whether the file is overwritten, supported image formats, or error conditions. For a 4-parameter tool, more context would be beneficial.

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% description coverage, so each parameter is already documented. The description adds minor value by mentioning optional use of reference images and the model default, but does not provide significant additional meaning beyond the schema. Baseline 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 edits a specific existing image file, optionally using reference images. It uses strong verbs ('Edit') and specifies the resource ('existing image file'), effectively distinguishing it from sibling tools like generate_image which creates new images.

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 provides usage context: 'Use this when you have the exact file path of an image to modify.' This gives clear guidance on when to invoke the tool, though it does not explicitly state when not to use it or list alternatives.

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

generate_imageA

Generate a NEW image from text prompt. Use this ONLY when creating a completely new image, not when modifying an existing one.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesText prompt describing the NEW image to create from scratch
modelNoOptional model name to use for image generation (e.g., 'gemini-3.1-flash-image' or 'gemini-3-pro-image'). Defaults to the value of environment variable GEMINI_IMAGE_MODEL, or 'gemini-3.1-flash-image' if unset.

TDQS

A4/5.0
Behavior3/5

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

No annotations provided; description only states creation purpose. Does not disclose side effects, auth needs, rate limits, or output format. Adequate for a simple create tool but minimal depth.

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?

Single sentence, front-loaded with key action, no wasted words. Perfectly concise.

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 2 parameters, no annotations, and no output schema, description covers core purpose and usage constraint. Missing return behavior (e.g., image URL or data) but sufficient for basic 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 good descriptions for both parameters. The tool description adds usage context but does not provide additional meaning beyond schema. Baseline 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?

Description clearly states 'Generate a NEW image from text prompt' with specific verb and resource. Explicitly distinguishes from modifications, differentiating from sibling edit_image.

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 states when to use: 'ONLY when creating a completely new image, not when modifying an existing one.' Lacks explicit mention of alternative edit_image but exclusion is clear.

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

get_configuration_statusA

Check if Gemini API token is configured

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior2/5

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

With no annotations, the description carries the full burden. It says 'Check if...' which implies a read-only operation, but it does not disclose whether this is a local check, whether it makes network calls, or what happens if the token is missingβ€”leaving the agent uncertain about side effects and behavior.

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?

One short sentence of 8 words. It is appropriately minimal for a zero-argument status check, with no wasted words.

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's simplicity, the description states the core action, but it lacks details on the return value or the meaning of 'configured' (e.g., environment variable present vs. valid API key). Since there's no output schema, this information is missing.

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 0 parameters, and the schema already reflects that with 100% coverage. The description doesn't need to explain any parameters, so the baseline 4 applies.

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 uses a specific verb ('Check'), names the resource ('Gemini API token'), and specifies the outcome ('is configured'). This clearly distinguishes it from siblings like configure_gemini_token (writes) and generate_image.

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 gives no explicit guidance on when to use this tool versus alternatives. It's implied that it's a status check for token configuration, but there's no mention of prerequisites or context (e.g., 'use before generating images').

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

get_last_image_infoA

Get information about the last generated/edited image in this session (file path, size, etc.). Use this to check what image is currently available for continue_editing.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

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

With no annotations provided, the description must convey behavioral context. It explains that the tool returns metadata about the last session image and ties it to the editing workflow, but it does not disclose edge cases (e.g., no image yet) or any potential side effects, leaving the behavioral profile somewhat incomplete.

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

Conciseness5/5

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

The description is two concise sentences, with the primary purpose stated upfront and the usage guidance in the second sentence. No superfluous content.

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

Completeness4/5

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

For a simple, parameterless tool, the description gives a good overview of its purpose and output. It mentions the kind of information returned (file path, size) and the appropriate context (before continue_editing), though it stops short of specifying behavior when no image exists. Given the lack of an output schema, this is adequate but not exhaustive.

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, and the schema is trivially complete (100% coverage). The description does not need to elaborate on parameters; it adds value by describing the output (file path, size, etc.), which satisfies the baseline for a parameterless tool.

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 uses a specific verb ('Get') and resource ('information about the last generated/edited image'), clearly distinguishing this read-only info tool from the generation/editing siblings. It also specifies the scope ('in this session') and hints at the output content (file path, size).

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 states when to use the tool: to check what image is currently available for continue_editing. It provides a clear use case but does not enumerate alternative tools or exclusion criteria, so it falls short of full 5.

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. 6 tool updatesv0.1.0
    • First observedconfigure_gemini_token
    • First observedcontinue_editing
    • First observededit_image
    • First observedgenerate_image
    • First observedget_configuration_status
    • First observedget_last_image_info

TDQS

A4.1/5.0

Scored across 6 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: configuration, generation, editing (with specific vs. last image), info retrieval, and status check. No overlap.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern, e.g., configure_gemini_token, generate_image, get_last_image_info.

Tool Count5/5

Six tools cover the core functionality of configuration, generation, editing, and status/info without being excessive or insufficient.

Completeness5/5

The toolset provides a complete workflow: configure token, generate image, edit specific or last image, and check configuration/status. No obvious gaps.

Maintenance

ActivityStale
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers