Nano Banana

Nano Banana manages image files using smart naming and automatic duplicate prevention.

Filename Generation

Images are saved with user-friendly names derived from your prompts (e.g., "sunset over mountains" becomes sunset_over_mountains.png). If a file with the same name exists, a counter is appended (e.g., sunset_over_mountains_1.png).

Output Directory

All generated images are automatically saved to the ./nanobanana-output/ directory, which is created by the extension if it does not exist.

Input File Search Locations

When performing editing or restoration tasks, the extension automatically searches for input images in the following locations in order:

1. Current working directory
2. ./images/ subdirectory
3. ./input/ subdirectory
4. ./nanobanana-output/ subdirectory
5. ~/Downloads/
6. ~/Desktop/

If you are developing the extension or the MCP server, use the following commands to manage the build process.

Project Root Commands

Use these to build the entire project or run the MCP server in development mode.

MCP Server Specific Commands

Navigate to the mcp-server directory to build or run the server standalone.

# Build the MCP server
npm run build

# Install MCP server dependencies
npm run install-deps

# Development mode with file watching
npm run dev

# --- MCP Server Specific ---

# Build MCP server directly
cd mcp-server && npm run build

# Start server standalone (for testing)
cd mcp-server && npm start

# Development mode with TypeScript watching
cd mcp-server && npm run dev

To use Nano Banana, you must first have the Gemini CLI installed and configured. Follow these steps to install and activate the extension:

1. Install the extension: Use the gemini extensions install command with the repository URL.
2. Activate: Restart your Gemini CLI session to make the new commands available.

Prerequisites:

• Gemini CLI: Installed and configured.
• Node.js 20+ and npm.
• API Key: You must set the NANOBANANA_API_KEY environment variable with your Gemini API key from Google AI Studio.

gemini extensions install https://github.com/gemini-cli-extensions/nanobanana

Nano Banana supports different Gemini models. By default, it uses gemini-3.1-flash-image-preview (Nano Banana 2). You can switch models by setting the NANOBANANA_MODEL environment variable.

Supported Models:

• gemini-3.1-flash-image-preview (Nano Banana 2 - default)
• gemini-3-pro-image-preview (Nano Banana Pro)
• gemini-2.5-flash-image (Nano Banana v1)

# Use Nano Banana Pro
export NANOBANANA_MODEL=gemini-3-pro-image-preview

# Use Nano Banana v1
export NANOBANANA_MODEL=gemini-2.5-flash-image

The system can automatically open generated images in your default system viewer. Control this behavior via the ImageGenerationRequest object:

• Explicit Preview: Set preview: true to open images after generation.
• Disable Preview: Set noPreview: true to prevent any images from opening.
• Default: If neither is set, images will not be automatically opened.

Nano Banana uses a hierarchical lookup for API keys. It will attempt to use the first valid key found in the following environment variables, in order:

1. NANOBANANA_API_KEY (Primary)
2. NANOBANANA_GEMINI_API_KEY (Fallback)
3. NANOBANANA_GOOGLE_API_KEY (Fallback)
4. GEMINI_API_KEY (Fallback)
5. GOOGLE_API_KEY (Fallback)

If no valid key is found, the system will throw an error. For more details, visit: https://geminicli.com/docs/get-started/authentication/

# Example: Setting the primary API key
export NANOBANANA_API_KEY='your_api_key_here'

If you encounter issues while using the extension, refer to these common solutions:

Command not recognized

Ensure the extension is located in ~/.gemini/extensions/nanobanana-extension/ and restart the Gemini CLI.

No API key found

Set the NANOBANANA_API_KEY environment variable:

Build failed

Ensure Node.js 18+ is installed, then run:

Image not found

Verify that your input files are located in one of the supported search directories (Current directory, ./images/, ./input/, ./nanobanana-output/, ~/Downloads/, or ~/Desktop/).

Debugging

The MCP server provides detailed debug logging that appears directly in the Gemini CLI console.

# Set the API key
export NANOBANANA_API_KEY="your-api-key-here"

# Fix build failures
npm run install-deps && npm run build

You can specify which Gemini model to use for image generation by setting the NANOBANANA_MODEL environment variable. If not provided, the system defaults to gemini-3.1-flash-image-preview.

# Example: Using a specific model
export NANOBANANA_MODEL='gemini-3.1-flash-image-preview'

Authentication for the MCP server is configured via the AuthConfig interface, which requires an apiKey.

const config: AuthConfig = {
  apiKey: 'YOUR_API_KEY'
};

The extension implements the Model Context Protocol (MCP) using JSON-RPC over stdio via the @modelcontextprotocol/sdk. It exposes the following tools to the Gemini CLI:

• generate_image: Creates a new image based on a prompt.
• edit_image: Modifies an existing image.
• restore_image: Restores or repairs an image.

If you provide an option with an unsupported value (e.g., an invalid size or an unrecognized style), the command will fail and return an error message. The error message will explicitly list the invalid options and provide the list of allowed values for each.

Common validation rules:

• --sizes must only contain integers from the allowed list: 16, 32, 64, 128, 256, 512, 1024.
• --type must be one of: app-icon, favicon, ui-element.
• --style must be one of: flat, skeuomorphic, minimal, modern.
• --format must be one of: png, jpeg.
• --corners must be one of: rounded, sharp.

If you provide an option that is not recognized or uses an invalid value (e.g., an unsupported style or an incorrect --size format), the command will fail and return an error message.

Common errors include:

• Using a --size format other than WxH (e.g., 256 instead of 256x256).
• Providing a value for --type, --style, --density, --colors, or --repeat that is not in the allowed list.

Error Format: Error: Invalid option(s) found: [list invalid options]. Valid options are: --size (format: WxH, e.g., 256x256), --type (seamless, texture, wallpaper), --style (geometric, organic, abstract, floral, tech), --density (sparse, medium, dense), --colors (mono, duotone, colorful), --repeat (tile, mirror), --preview (flag)