🎨 Gemini Nanobanana MCP

Generate images from text with Claude! Simply type "Draw a cute cat" and get instant AI-generated images.

A beginner-friendly Model Context Protocol (MCP) server that brings Google's Gemini 2.5 Flash Image generation directly into your Claude conversations.

Quick Start - Just 3 Steps

1️⃣ Get Your API Key (1 minute)

Visit Google AI Studio
Sign in with your Google account
Click "Create API key" → Copy the key

2️⃣ Install in Your Claude Client (2 minutes)

Claude Desktop (Windows)

Open Notepad
Copy this code and replace YOUR_API_KEY with your actual key:

{
  "mcpServers": {
    "gemini-nanobanana-mcp": {
      "command": "npx",
      "args": ["gemini-nanobanana-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Save as: %APPDATA%/Claude/claude_desktop_config.json
Restart Claude Desktop

Claude Desktop (Mac)

Open Terminal (search "Terminal" in Spotlight)
Run this command (replace YOUR_API_KEY):

cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json << 'EOF'
{
  "mcpServers": {
    "gemini-nanobanana-mcp": {
      "command": "npx",
      "args": ["gemini-nanobanana-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
EOF

Restart Claude Desktop

Claude Code (Easiest!)

Just run this one command in your terminal (replace YOUR_API_KEY):

claude mcp add gemini-nanobanana-mcp -s user -e GEMINI_API_KEY="YOUR_API_KEY" -- npx -y gemini-nanobanana-mcp@latest

Cursor

Go to Cursor Settings → MCP → Add new MCP Server
Fill in:
- Name: gemini-nanobanana-mcp
- Command: npx
- Args: gemini-nanobanana-mcp@latest
- Environment Variables: GEMINI_API_KEY = YOUR_API_KEY
Restart Cursor

3️⃣ Start Creating! (0 minutes)

Try these in Claude:

"Generate a cute puppy playing in a garden"
"Create a beautiful sunset over mountains"
"Draw a red sports car"
"Make an abstract colorful painting"

Your images automatically save to ~/Downloads/gemini-images/

See It In Action

Basic Usage

You: Generate a cozy coffee shop interior
Claude: [Generating image...]
Image generated and saved to: ~/Downloads/gemini-images/generate-2025-01-09-14-30-45.png
Size: 1.2MB | Format: PNG

Custom Save Location

You: Create a sunset landscape and save it as ./my-sunset.png
Claude: Image saved to: ./my-sunset.png

What You Can Do

Text-to-Image Generation

Create any image you can imagine from a text description.

Examples:

"A majestic dragon flying over a medieval castle"
"Modern minimalist living room with plants"
"Vintage bicycle on a cobblestone street"

Image Editing

Edit existing images with natural language instructions.

How to use:

Upload an image to Claude
Say: "Make this image black and white"
Or: "Add a sunset background to this photo"

Image Composition

Combine multiple images into one creative composition.

How to use:

Upload 2-10 images to Claude
Say: "Combine these images into a collage"
Or: "Blend these photos together artistically"

Style Transfer

Apply the artistic style of one image to another.

How to use:

Upload two images: a content image and a style reference
Say: "Apply the style of the second image to the first"

Configuration Options

Environment Variables

Variable	Default	Description
`GEMINI_API_KEY`	Required	Your Google AI Studio API key
`AUTO_SAVE`	`true`	Automatically save images when no path specified
`DEFAULT_SAVE_DIR`	`~/Downloads/gemini-images`	Default directory for saved images
`LOG_LEVEL`	`info`	Logging level (`error`, `warn`, `info`, `debug`)

Example with custom settings:

{
  "mcpServers": {
    "gemini-nanobanana-mcp": {
      "command": "npx",
      "args": ["gemini-nanobanana-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key",
        "AUTO_SAVE": "true",
        "DEFAULT_SAVE_DIR": "~/Pictures/AI-Images",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Disable Auto-Save

To only save when you explicitly request it:

{
  "env": {
    "GEMINI_API_KEY": "your-api-key",
    "AUTO_SAVE": "false"
  }
}

Then images will only appear in the chat without saving to disk.

Instant Image Preview (Claude Code)

Want images to open automatically after generation? Set up Claude Code hooks for instant Quick Look previews!

One-Click Setup (Mac)

# Clone this repo and run the installer
git clone https://github.com/nanobanana/nanobanana-mcp.git
cd nanobanana-mcp
bash hooks/install.sh

What You Get

Instant Preview: Generated images open automatically in Quick Look
Zero Manual Work: No more finding and opening files
Smart Detection: Only triggers for nanobanana image tools
Press Space to Close: Standard Quick Look controls

Full setup guide: hooks/README.md

Troubleshooting

❌ "GEMINI_API_KEY not set" error

Solution:

Double-check you replaced YOUR_API_KEY with your actual API key
Make sure there are no extra spaces around the key
Restart your Claude client completely
Verify your API key works at Google AI Studio

"No such file or directory" error

Solution:

Install Node.js from nodejs.org (choose LTS version)
Restart your terminal/Claude client
Try the installation again

Images not generating

Checklist:

API key correctly set?
Internet connection working?
Restart Claude after configuration?
Try a simple prompt: "Generate a blue circle"

Images not saving automatically

Solution: Check your configuration has AUTO_SAVE: "true" (default behavior). If you want to disable auto-save, set it to "false".

Hook setup not working

Common fixes:

Make sure you're using Claude Code (not Claude Desktop)
Run the installer from the nanobanana-mcp directory
Restart Claude Code after installation
Check hooks/README.md for detailed troubleshooting

Tips for Better Images

Prompt Writing Tips

Be specific: "A golden retriever puppy" vs "A dog"
Include style: "in watercolor style", "photorealistic", "cartoon style"
Add details: "with blue eyes", "in a sunny garden", "wearing a red collar"
Set the mood: "cozy", "dramatic", "peaceful", "energetic"

Technical Details

Supported formats: PNG, JPEG, WebP, GIF
Default output: PNG format
Image size: Optimized for quality and reasonable file size
Rate limits: Managed automatically with retry logic

🚀 Advanced Features

🔗 HTTP Mode (for integrations)

Run as an HTTP server instead of stdio:

MCP_TRANSPORT=http MCP_HTTP_PORT=8080 npx gemini-nanobanana-mcp@latest

Access at http://localhost:8080/mcp

📊 Debug Logging

Enable detailed logging:

{
  "env": {
    "GEMINI_API_KEY": "your-key",
    "LOG_LEVEL": "debug"
  }
}

💡 Need Help?

📖 Quick Setup Guide: QUICK_START.md
🪝 Auto-Preview Setup: hooks/README.md
🐛 Report Issues: GitHub Issues
💬 Feature Requests: Welcome!

🤝 Contributing

Found a bug? Have a feature idea? Contributions are welcome!

Fork the repository
Create your feature branch
Make your changes
Submit a pull request

📄 License

MIT License - feel free to use this in your own projects!

⭐ If this helped you, please star the repository on GitHub!

Built with ❤️ for the Claude community

🎨 Gemini Nanobanana MCP

Generate images from text with Claude! Simply type "Draw a cute cat" and get instant AI-generated images.

A beginner-friendly Model Context Protocol (MCP) server that brings Google's Gemini 2.5 Flash Image generation directly into your Claude conversations.

Quick Start - Just 3 Steps

1️⃣ Get Your API Key (1 minute)

Visit Google AI Studio
Sign in with your Google account
Click "Create API key" → Copy the key

2️⃣ Install in Your Claude Client (2 minutes)

Claude Desktop (Windows)

Open Notepad
Copy this code and replace YOUR_API_KEY with your actual key:

{
  "mcpServers": {
    "gemini-nanobanana-mcp": {
      "command": "npx",
      "args": ["gemini-nanobanana-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Save as: %APPDATA%/Claude/claude_desktop_config.json
Restart Claude Desktop

Claude Desktop (Mac)

Open Terminal (search "Terminal" in Spotlight)
Run this command (replace YOUR_API_KEY):

cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json << 'EOF'
{
  "mcpServers": {
    "gemini-nanobanana-mcp": {
      "command": "npx",
      "args": ["gemini-nanobanana-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
EOF

Restart Claude Desktop

Claude Code (Easiest!)

Just run this one command in your terminal (replace YOUR_API_KEY):

claude mcp add gemini-nanobanana-mcp -s user -e GEMINI_API_KEY="YOUR_API_KEY" -- npx -y gemini-nanobanana-mcp@latest

Cursor

Go to Cursor Settings → MCP → Add new MCP Server
Fill in:
- Name: gemini-nanobanana-mcp
- Command: npx
- Args: gemini-nanobanana-mcp@latest
- Environment Variables: GEMINI_API_KEY = YOUR_API_KEY
Restart Cursor

3️⃣ Start Creating! (0 minutes)

Try these in Claude:

"Generate a cute puppy playing in a garden"
"Create a beautiful sunset over mountains"
"Draw a red sports car"
"Make an abstract colorful painting"

Your images automatically save to ~/Downloads/gemini-images/

See It In Action

Basic Usage

You: Generate a cozy coffee shop interior
Claude: [Generating image...]
Image generated and saved to: ~/Downloads/gemini-images/generate-2025-01-09-14-30-45.png
Size: 1.2MB | Format: PNG

Custom Save Location

You: Create a sunset landscape and save it as ./my-sunset.png
Claude: Image saved to: ./my-sunset.png

What You Can Do

Text-to-Image Generation

Create any image you can imagine from a text description.

Examples:

"A majestic dragon flying over a medieval castle"
"Modern minimalist living room with plants"
"Vintage bicycle on a cobblestone street"

Image Editing

Edit existing images with natural language instructions.

How to use:

Upload an image to Claude
Say: "Make this image black and white"
Or: "Add a sunset background to this photo"

Image Composition

Combine multiple images into one creative composition.

How to use:

Upload 2-10 images to Claude
Say: "Combine these images into a collage"
Or: "Blend these photos together artistically"

Style Transfer

Apply the artistic style of one image to another.

How to use:

Upload two images: a content image and a style reference
Say: "Apply the style of the second image to the first"

Configuration Options

Environment Variables

Variable	Default	Description
`GEMINI_API_KEY`	Required	Your Google AI Studio API key
`AUTO_SAVE`	`true`	Automatically save images when no path specified
`DEFAULT_SAVE_DIR`	`~/Downloads/gemini-images`	Default directory for saved images
`LOG_LEVEL`	`info`	Logging level (`error`, `warn`, `info`, `debug`)

Example with custom settings:

{
  "mcpServers": {
    "gemini-nanobanana-mcp": {
      "command": "npx",
      "args": ["gemini-nanobanana-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key",
        "AUTO_SAVE": "true",
        "DEFAULT_SAVE_DIR": "~/Pictures/AI-Images",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Disable Auto-Save

To only save when you explicitly request it:

{
  "env": {
    "GEMINI_API_KEY": "your-api-key",
    "AUTO_SAVE": "false"
  }
}

Then images will only appear in the chat without saving to disk.

Instant Image Preview (Claude Code)

Want images to open automatically after generation? Set up Claude Code hooks for instant Quick Look previews!

One-Click Setup (Mac)

# Clone this repo and run the installer
git clone https://github.com/nanobanana/nanobanana-mcp.git
cd nanobanana-mcp
bash hooks/install.sh

What You Get

Instant Preview: Generated images open automatically in Quick Look
Zero Manual Work: No more finding and opening files
Smart Detection: Only triggers for nanobanana image tools
Press Space to Close: Standard Quick Look controls

Full setup guide: hooks/README.md

Troubleshooting

❌ "GEMINI_API_KEY not set" error

Solution:

Double-check you replaced YOUR_API_KEY with your actual API key
Make sure there are no extra spaces around the key
Restart your Claude client completely
Verify your API key works at Google AI Studio

"No such file or directory" error

Solution:

Install Node.js from nodejs.org (choose LTS version)
Restart your terminal/Claude client
Try the installation again

Images not generating

Checklist:

API key correctly set?
Internet connection working?
Restart Claude after configuration?
Try a simple prompt: "Generate a blue circle"

Images not saving automatically

Solution: Check your configuration has AUTO_SAVE: "true" (default behavior). If you want to disable auto-save, set it to "false".

Hook setup not working

Common fixes:

Make sure you're using Claude Code (not Claude Desktop)
Run the installer from the nanobanana-mcp directory
Restart Claude Code after installation
Check hooks/README.md for detailed troubleshooting

Tips for Better Images

Prompt Writing Tips

Be specific: "A golden retriever puppy" vs "A dog"
Include style: "in watercolor style", "photorealistic", "cartoon style"
Add details: "with blue eyes", "in a sunny garden", "wearing a red collar"
Set the mood: "cozy", "dramatic", "peaceful", "energetic"

Technical Details

Supported formats: PNG, JPEG, WebP, GIF
Default output: PNG format
Image size: Optimized for quality and reasonable file size
Rate limits: Managed automatically with retry logic

🚀 Advanced Features

🔗 HTTP Mode (for integrations)

Run as an HTTP server instead of stdio:

MCP_TRANSPORT=http MCP_HTTP_PORT=8080 npx gemini-nanobanana-mcp@latest

Access at http://localhost:8080/mcp

📊 Debug Logging

Enable detailed logging:

{
  "env": {
    "GEMINI_API_KEY": "your-key",
    "LOG_LEVEL": "debug"
  }
}

💡 Need Help?

📖 Quick Setup Guide: QUICK_START.md
🪝 Auto-Preview Setup: hooks/README.md
🐛 Report Issues: GitHub Issues
💬 Feature Requests: Welcome!

🤝 Contributing

Found a bug? Have a feature idea? Contributions are welcome!

Fork the repository
Create your feature branch
Make your changes
Submit a pull request

📄 License

MIT License - feel free to use this in your own projects!

⭐ If this helped you, please star the repository on GitHub!

Built with ❤️ for the Claude community