๐ ๐จ Gemini Nanobanana MCP
A beginner-friendly Model Context Protocol (MCP) server that integrates Google's Gemini 2.5 Flash Image generation into your Claude conversations, enabling text-to-image generation.
๐ Quick Start
1๏ธโฃ Obtain Your API Key (1 minute)
- Navigate to Google AI Studio.
- Sign in using your Google account.
- Click "Create API key" and copy the key.
2๏ธโฃ Install in Your Claude Client (2 minutes)
Claude Desktop (Windows)
- Open Notepad.
- Copy the following 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 the file as
%APPDATA%/Claude/claude_desktop_config.json.
- Restart Claude Desktop.
Claude Desktop (Mac)
- Open Terminal (search "Terminal" in Spotlight).
- Execute the following 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!)
Run the following 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
- Navigate to
Cursor Settings โ MCP โ Add new MCP Server.
- Fill in the following details:
- 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 the following prompts 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 will be automatically saved to ~/Downloads/gemini-images/
๐ป Usage Examples
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
โจ Features
Text-to-Image Generation
Generate 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 using 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 a single 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"
๐ฆ Installation
Configuration Options
Environment Variables
| Property |
Details |
GEMINI_API_KEY |
Required. Your Google AI Studio API key |
AUTO_SAVE |
true. Automatically save images when no path is 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 save images only when explicitly requested:
{
"env": {
"GEMINI_API_KEY": "your-api-key",
"AUTO_SAVE": "false"
}
}
Images will then only appear in the chat without being saved to disk.
๐ Documentation
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)
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 need to manually find and open 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 that you replaced
YOUR_API_KEY with your actual API key.
- Ensure there are no extra spaces around the key.
- Completely restart your Claude client.
- Verify that your API key works at Google AI Studio.
"No such file or directory" error
Solution:
- Install Node.js from nodejs.org (choose the LTS version).
- Restart your terminal/Claude client.
- Try the installation again.
Images not generating
Checklist:
- Is the API key set correctly?
- Is your internet connection working?
- Did you restart Claude after configuration?
- Try a simple prompt: "Generate a blue circle".
Images not saving automatically
Solution:
Check that 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" is better than "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.
๐ง Technical Details
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
This project is licensed under the MIT License. You are free to use it in your own projects!
โญ If this project has helped you, please star the repository on GitHub!
Built with โค๏ธ for the Claude community