Nano-Banana MCP Server 🍌

Free & open-source MCP server for AI image generation and editing, powered by Google Gemini.

Generate stunning images, edit existing ones, and iterate on your creations — all through natural language prompts. Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client.

✨ Features

• 🎨 Generate Images — Create new images from text descriptions
• ✏️ Edit Images — Modify existing images with natural language instructions
• 🔄 Multi-Turn Editing — Continue refining with full conversation history
• 🧩 Reference Images — Add visual references for style, characters, objects, or composition
• 📐 Aspect Ratios — Square, portrait, landscape, widescreen, stories
• 🖼️ Resolutions — From 512px to 4K
• 🤖 3 Models — Fast, balanced, and pro quality tiers
• 🔧 Zero Config — Just add your free Gemini API key and go

🤖 Available Models

🚀 Quick Start

npm install -g mcp-nanobanana

Or run directly without installing:

npx mcp-nanobanana

That's it — just add your free Gemini API key and configure your MCP client (see below).

🔑 Setup

1. Get your Gemini API key (free)

• Visit Google AI Studio
• Create a new API key
• Copy it for configuration

2. Configure your MCP client

Pick your client below and add the configuration.

💻 Usage with Claude Code

Run this in your terminal:

claude mcp add nanobanana -e GEMINI_API_KEY="your-gemini-api-key-here" -- npx mcp-nanobanana

Tip: Add -y after npx to skip the install confirmation prompt (npx -y mcp-nanobanana). Without it, npx will ask you to confirm before downloading the package the first time.

Or manually add to your MCP settings (~/.claude/settings.json):

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

Usage Examples

Generate an image of a sunset over mountains in 4K widescreen

Edit this image to add some birds in the sky

Continue editing — make it more dramatic

🧩 Companion Skill

For the best experience with Claude Code, install the nanobanana-skill — it teaches Claude how to pick the right tool, enhance prompts, and handle aspect ratios automatically:

npx skills add caio-rodrigo-silva/nanobanana-skill

🧠 Usage with Codex

codex mcp add nanobanana --env GEMINI_API_KEY="your-gemini-api-key-here" -- mcp-nanobanana

Or without installing globally:

codex mcp add nanobanana --env GEMINI_API_KEY="your-gemini-api-key-here" -- npx mcp-nanobanana

Optionally set a custom output directory:

codex mcp add nanobanana \
  --env GEMINI_API_KEY="your-gemini-api-key-here" \
  --env NANOBANANA_OUTPUT_DIR="/path/to/output" \
  -- mcp-nanobanana

Verify with:

codex mcp list
codex mcp get nanobanana

For the best experience, copy AGENTS.md from nanobanana-skill into your project root.

🎯 Usage with Cursor

Add to your Cursor MCP configuration:

{
  "nanobanana": {
    "command": "npx",
    "args": ["mcp-nanobanana"],
    "env": {
      "GEMINI_API_KEY": "your-gemini-api-key-here"
    }
  }
}

🔧 For Other MCP Clients

Works with any MCP-compatible client. Use the same configuration pattern:

Option A: Environment variable in MCP config (recommended)

{
  "nanobanana": {
    "command": "npx",
    "args": ["mcp-nanobanana"],
    "env": {
      "GEMINI_API_KEY": "your-gemini-api-key-here"
    }
  }
}

Option B: System environment variable

export GEMINI_API_KEY="your-gemini-api-key-here"
npx mcp-nanobanana

🛠️ Available Tools

generate_image

Create a new image from a text prompt.

generate_image({
  prompt: "A futuristic city at night with neon lights",
  referenceImages: ["/path/to/style-reference.png"], // optional
  model: "nano-banana-pro",  // optional
  aspectRatio: "16:9",       // optional
  imageSize: "4K"            // optional
})

edit_image

Edit an existing image with text instructions.

edit_image({
  imagePath: "/path/to/image.png",
  prompt: "Add a rainbow in the sky",
  referenceImages: ["/path/to/rainbow-reference.jpg"], // optional
  model: "nano-banana-2",  // optional
  aspectRatio: "4:3",      // optional
  imageSize: "2K"          // optional
})

continue_editing

Continue editing the last generated/edited image — no need to specify a file path. The server sends the current conversation history so the model can preserve context across iterations.

continue_editing({
  prompt: "Make it more colorful",
  referenceImages: ["/path/to/color-reference.webp"], // optional
  aspectRatio: "1:1",  // optional
  imageSize: "2K"      // optional
})

new_session

Clear the current multi-turn editing session without generating a new image.

new_session()

get_last_image

Get information about the last generated/edited image.

get_last_image()

get_status

Check if the API key is configured and list available models.

get_status()

configure_api_key

Set the Gemini API key at runtime (alternative to environment variable).

configure_api_key({
  apiKey: "your-gemini-api-key"
})

📐 Image Options

Aspect Ratios

Resolutions

Reference Images

generate_image, edit_image, and continue_editing accept an optional referenceImages array.

generate_image({
  prompt: "Create a product hero image using the lighting and color mood from the reference",
  referenceImages: ["/absolute/path/to/reference.png"],
  aspectRatio: "16:9",
  imageSize: "2K"
})

Use reference images when the prompt needs visual context, such as:

• Matching a person's appearance
• Preserving a product shape or object
• Reusing a lighting style, color palette, or composition
• Adding a visual element similar to a provided photo

Always pass absolute file paths.

🔄 Multi-Turn Sessions

The server keeps conversation history for image iteration:

• generate_image starts a new session
• edit_image starts a new session with the provided image
• continue_editing adds a new turn to the current session
• new_session clears the current session

This improves iterative workflows because the model can see the previous prompts and generated image parts instead of only receiving the last saved image.

📁 Output

Images are saved to ./nanobanana-images/ relative to your working directory.

You can customize the output directory with the NANOBANANA_OUTPUT_DIR environment variable.

🎨 Example Workflows

Quick Image Generation

1. generate_image — Create your base image
2. continue_editing — Refine and improve with session context
3. continue_editing — Add final touches

Editing an Existing Photo

1. edit_image — Apply changes to your image
2. continue_editing — Fine-tune the result
3. get_last_image — Check the output path

Iterative Design

1. generate_image — Start with a concept
2. continue_editing — Make adjustments
3. Repeat until satisfied

Reference-Guided Editing

1. edit_image — Start from an existing image
2. Add referenceImages for a person, product, style, or object
3. continue_editing — Add more references at any turn when needed

🔧 Development

# Clone the repository
git clone https://github.com/caio-rodrigo-silva/mcp-nanobanana.git
cd mcp-nanobanana

# Install dependencies
npm install

# Build
npm run build

# Development with auto-rebuild
npm run dev

Tech Stack

• TypeScript — Type-safe development
• Node.js — Runtime environment
• Zod — Schema validation
• @google/genai — Google Gemini API
• @modelcontextprotocol/sdk — MCP protocol

📋 Requirements

• Node.js 18+
• Gemini API key from Google AI Studio (free)
• Any MCP-compatible client

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📄 License

MIT License — see LICENSE file for details.

🔗 Links

• 🐛 Issues: GitHub Issues
• 🧩 Companion Skill: nanobanana-skill
• 📖 Gemini API: Google AI Studio

Made with 🍌 by Caio Rodrigo