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
🔄 Iterative Editing — Continue refining the last generated/edited image
📐 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

| Alias | Gemini Model | Best For | |-------|-------------|----------| | nano-banana | gemini-2.5-flash-image | Fast drafts & previews | | nano-banana-2 | gemini-3.1-flash-image-preview | Balanced quality (default) | | nano-banana-pro | gemini-3-pro-image-preview | Highest quality results |

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

continue_editing({
  prompt: "Make it more colorful",
  aspectRatio: "1:1",  // optional
  imageSize: "2K"      // optional
})

`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

| Value | Use Case | |-------|----------| | 1:1 | Square — social media posts, avatars | | 3:4 | Portrait — vertical photos | | 4:3 | Landscape — horizontal photos | | 9:16 | Stories — Instagram/TikTok reels, phone screens | | 16:9 | Widescreen — presentations, cinematic |

Resolutions

| Value | Notes | |-------|-------| | 512 | Fast preview (only on nano-banana-2) | | 1K | Standard quality (default) | | 2K | High quality | | 4K | Maximum quality |

📁 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

generate_image — Create your base image
continue_editing — Refine and improve
continue_editing — Add final touches

Editing an Existing Photo

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

Iterative Design

generate_image — Start with a concept
continue_editing — Make adjustments
Repeat until satisfied

🔧 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

MCP Servers

Nano-Banana MCP Server 🍌

✨ Features

🤖 Available Models

🚀 Quick Start

🔑 Setup

1. Get your Gemini API key (free)

2. Configure your MCP client

💻 Usage with Claude Code

Usage Examples

🧩 Companion Skill

🧠 Usage with Codex

🎯 Usage with Cursor

🔧 For Other MCP Clients

🛠️ Available Tools

`generate_image`

`edit_image`

`continue_editing`

`get_last_image`

`get_status`

`configure_api_key`

📐 Image Options

Aspect Ratios

Resolutions

📁 Output

🎨 Example Workflows

Quick Image Generation

Editing an Existing Photo

Iterative Design

🔧 Development

Tech Stack

📋 Requirements

🤝 Contributing

📄 License

🔗 Links

安装包（如果需要）

Cursor 配置 (mcp.json)

Nano-Banana MCP Server 🍌

✨ Features

🤖 Available Models

🚀 Quick Start

🔑 Setup

1. Get your Gemini API key (free)

2. Configure your MCP client

💻 Usage with Claude Code

Usage Examples

🧩 Companion Skill

🧠 Usage with Codex

🎯 Usage with Cursor

🔧 For Other MCP Clients

🛠️ Available Tools

generate_image

edit_image

continue_editing

get_last_image

get_status

configure_api_key

📐 Image Options

Aspect Ratios

Resolutions

📁 Output

🎨 Example Workflows

Quick Image Generation

Editing an Existing Photo

Iterative Design

🔧 Development

Tech Stack

📋 Requirements

🤝 Contributing

📄 License

🔗 Links

安装包 （如果需要）

Cursor 配置 (mcp.json)

`generate_image`

`edit_image`

`continue_editing`

`get_last_image`

`get_status`

`configure_api_key`

安装包（如果需要）