🎨 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)

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

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

<details> <summary><b>Claude Desktop (Windows)</b></summary>

1. Open Notepad
2. 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"
      }
    }
  }
}

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

</details>

<details> <summary><b>Claude Desktop (Mac)</b></summary>

1. Open Terminal (search "Terminal" in Spotlight)
2. 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

3. Restart Claude Desktop

</details>

<details> <summary><b>Claude Code (Easiest!)</b></summary>

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

</details>

<details> <summary><b>Cursor</b></summary>

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

</details>

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

<details> <summary><b>Environment Variables</b></summary>

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"
      }
    }
  }
}

</details>

<details> <summary><b>Disable Auto-Save</b></summary>

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.

</details>

---

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

<details> <summary><b>❌ "GEMINI_API_KEY not set" error</b></summary>

Solution:

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

</details>

<details> <summary><b>"No such file or directory" error</b></summary>

Solution:

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

</details>

<details> <summary><b>Images not generating</b></summary>

Checklist:

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

</details>

<details> <summary><b>Images not saving automatically</b></summary>

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

</details>

<details> <summary><b>Hook setup not working</b></summary>

Common fixes:

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

</details>

---

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

<details> <summary><b>🔗 HTTP Mode (for integrations)</b></summary>

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

</details>

<details> <summary><b>📊 Debug Logging</b></summary>

Enable detailed logging:

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

</details>

---

💡 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!

1. Fork the repository
2. Create your feature branch
3. Make your changes
4. 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