Skip to main content
Glama
Junhan2

Gemini Nanobanana MCP

by Junhan2
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Hybrid

🎨 Gemini Nanobanana MCP

npm version License: MIT TypeScript Node.js

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)

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

  1. Save as: %APPDATA%/Claude/claude_desktop_config.json

  2. Restart Claude Desktop

  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

  1. Restart Claude Desktop

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

  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

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/

Related MCP server: Gemini 2.5 Flash Image MCP

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

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

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

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

Solution:

  1. Install Node.js from nodejs.org (choose LTS version)

  2. Restart your terminal/Claude client

  3. Try the installation again

Checklist:

  • API key correctly set?

  • Internet connection working?

  • Restart Claude after configuration?

  • Try a simple prompt: "Generate a blue circle"

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

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

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

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

Enable detailed logging:

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

💡 Need Help?

🤝 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

Available Tools

4 tools
compose_imagesC

Compose a new image using multiple input images and a guiding prompt.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesDescribe how to compose the elements of the input images.
imagesYes
saveToFilePathNoOptional path to save the composed image

TDQS

C2.6/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description offers no behavioral details such as output format, side effects, or required permissions. Only restates purpose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, efficient but too minimal. Could be expanded with key behavioral info without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Lacks output schema and annotations. Does not explain return value or behavior. Severely incomplete for a tool with 3 parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Description adds minimal value to schema: 'multiple input images' is redundant with schema. The prompt description is less informative than the schema's detailed description. Missing schema coverage for images items not compensated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (compose) and resource (new image), using multiple input images and a guiding prompt. It distinguishes from sibling tools: edit_image edits existing, generate_image creates from scratch, style_transfer applies style.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. Lacks explicit context or when-not-to-use conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

edit_imageA

Edit an image using a prompt. Provide one input image via base64 or file path.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesDescribe the edit; the model matches original style and lighting.
imageYesOne input image
saveToFilePathNoOptional path to save the edited image

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions the model matches original style and lighting, a useful behavioral trait, but omits potential side effects, limitations, or output details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (two short sentences) with no extraneous information. It could be slightly improved by front-loading the core action, but it's very efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description lacks information about the return value (e.g., whether the edited image is returned as base64 or saved to a path). This gap in completeness moderately hampers agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description restates what is already in the schema (e.g., 'provide one input image via base64 or file path') without adding significant new meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (edit), resource (image), and method (prompt). It distinguishes from siblings like 'generate_image' and 'compose_images' by focusing on editing an existing image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool vs. alternatives. While sibling names provide context, the description itself lacks explicit usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_imageB

Generate an image from a text prompt using Gemini 2.5 Flash Image

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesDetailed scene description. Use photographic terms for photorealism.
saveToFilePathNoOptional path to save the image (png/jpeg by extension)

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and description only restates the model name. Missing behavioral details like synchronicity, latency, rate limits, or cost implications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence that is front-loaded and to the point. Could include more detail without being verbose, but no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, no description of return value (e.g., URL, base64). Lacks context on capabilities of the model or when to prefer this over siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters. Description adds value by suggesting 'use photographic terms for photorealism' for prompt, and clarifying file extension for saveToFilePath.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states action ('generate'), resource ('image'), and method ('from text prompt using Gemini 2.5 Flash Image'). Distinguishes from sibling tools (compose, edit, style transfer).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs siblings like compose_images or edit_image. No when-not or alternative scenarios mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

style_transferB

Transfer style from a style image to a base image, guided by an optional prompt.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptNoOptional additional instruction for the style transfer.
baseImageYes
styleImageYes
saveToFilePathNoOptional path to save the output

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that style is transferred, but omits important details such as potential image size/resolution constraints, output format, and whether the operation is deterministic or requires significant computation. This is insufficient for an AI agent to anticipate side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that efficiently conveys the core function. Every word contributes to understanding, with no unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite moderate complexity (4 parameters, nested images, no output schema), the description fails to provide adequate context. It does not specify the output format (e.g., generated image returned inline or saved to path), behavior when prompt is omitted, or any error conditions. This leaves significant gaps for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50% (prompt and saveToFilePath have descriptions; baseImage and styleImage do not). The tool description adds no additional parameter meaning beyond the schema—it merely restates 'optional prompt'. Given the presence of nested image objects without detailed parameter descriptions, the description should have clarified expected image formats or requirements.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('transfer') and clearly identifies the resources ('style image', 'base image'), making the tool's function unambiguous. It also distinguishes this tool from siblings like 'compose_images' or 'edit_image' by explicitly mentioning style transfer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used for style transfer tasks, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., compose_images, edit_image). No usage restrictions or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv0.1.7
    • First observedcompose_images
    • First observededit_image
    • First observedgenerate_image
    • First observedstyle_transfer
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation5/5

Each tool targets a distinct image operation: generating from scratch, editing, composing multiple images, and style transfer. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with snake_case (e.g., compose_images, edit_image). No deviations.

Tool Count5/5

Four tools cover essential image generation capabilities without being sparse or overloaded. The scope is well-balanced.

Completeness4/5

Core image workflows (generation, editing, composition, style transfer) are covered. Minor gaps like cropping or deletion exist but are non-essential for the server's purpose.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Junhan2/gemini-nanobanana-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server