mcp-nano-banana-image

Generate images using Google Gemini (Nano Banana) models.

Available as both an MCP Server and a Claude Code Skill.

Claude Code Skill

Zero-dependency standalone skill for Claude Code. No npm install needed — uses Node.js 18+ built-in fetch.

Setup

Copy the skill/nano-banana-generate-image/ directory to your project:

cp -r skill/nano-banana-generate-image <your-project>/.claude/skills/

Set credentials (pick one, gateway preferred):

# Recommended — route through Botrun Gateway (no Gemini key needed; all requests go through the gateway)
export BOTRUN_GATE_BASE_URL="https://gate.botrun.ai"
export BOTRUN_GATE_API_KEY="br-your-key"

# Or — direct to Google AI (fallback)
export GEMINI_API_KEY="your-api-key"

When both BOTRUN_GATE_* are set the skill routes through the gateway's /gemini/* passthrough (Vertex ADC behind it); otherwise it uses GEMINI_API_KEY / GOOGLE_API_KEY directly. There is no runtime fallback between the two — selection is by environment variables.

Usage

In Claude Code, type /nano-banana-generate-image or simply ask Claude to generate/edit an image.

CLI Usage

You can also run the script directly:

node .claude/skills/nano-banana-generate-image/nano-banana-generate-image.js \
  --prompt "A cute cat" \
  --output-dir "./gen-images" \
  [--image-path "ref.png"] \
  [--model "gemini-2.5-flash-image"]

MCP Server

Installation

npm install @modelcontextprotocol/sdk @google/genai zod
npm install -D typescript @types/node

Build

npm run build

Configuration

Environment Variables

Pick one credential path (gateway preferred). Selection is by environment variables — no runtime fallback.

| Variable | Description | |----------|-------------| | BOTRUN_GATE_BASE_URL | Botrun Gateway base URL, e.g. https://gate.botrun.ai (recommended) | | BOTRUN_GATE_API_KEY | Gateway br- API key (sent as Authorization: Bearer) | | GEMINI_API_KEY | Google AI API Key — direct path (fallback) | | GOOGLE_API_KEY | Alternative direct API key name |

When both BOTRUN_GATE_* are set, the server points the @google/genai SDK at the gateway's /gemini/* passthrough (baseUrl = ${BOTRUN_GATE_BASE_URL}/gemini, auth via Authorization: Bearer); otherwise the SDK reads GEMINI_API_KEY / GOOGLE_API_KEY and calls Google directly.

Claude Desktop Integration

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nano-banana-image": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "BOTRUN_GATE_BASE_URL": "https://gate.botrun.ai",
        "BOTRUN_GATE_API_KEY": "br-your-key"
      }
    }
  }
}

Tool: generate_image

Generate images using Google Gemini models.

Input Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | prompt | string | Yes | - | Image generation prompt | | image_path | string | No | - | Reference image path (for image editing) | | model | string | No | gemini-2.5-flash-image | Gemini model to use | | output_dir | string | Yes | - | Output directory for generated images |

Output

{
  "file_paths": [
    "/path/to/output/generated_a1b2c3_1702345678901.png"
  ],
  "usage_metadata": {
    "prompt_tokens": 22,
    "completion_tokens": 1553,
    "total_tokens": 1575,
    "thoughts_tokens": 292,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "model": "gemini/gemini-2.5-flash-image"
  },
  "text_response": "Optional text response from the model"
}

usage_metadata Fields

| Field | Description | |-------|-------------| | prompt_tokens | Input token count | | completion_tokens | Output token count (includes thinking tokens) | | total_tokens | Total token count | | thoughts_tokens | Thinking/reasoning token count (Gemini 3 models) | | cache_creation_input_tokens | Cache creation token count | | cache_read_input_tokens | Cached content token count | | model | Model name in LiteLLM format for cost calculation |

Available Models

| Model | Description | |-------|-------------| | gemini-2.5-flash-image | Fast image generation (default) | | gemini-3-pro-image | High quality image generation (Nano Banana Pro) |

Testing

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

License

MIT