Skip to main content
Glama
bongartzdiaz

Nano-Banana MCP Server

by bongartzdiaz

Nano-Banana MCP Server 🍌

πŸ€– This project was entirely generated by Claude Code - an AI coding assistant that can create complete, production-ready applications from scratch.

A Model Context Protocol (MCP) server that provides AI image generation and editing capabilities using Google's Gemini 2.5 Flash Image API. Generate stunning images, edit existing ones, and iterate on your creations with simple text prompts.

✨ Features

  • 🎨 Generate Images: Create new images from text descriptions

  • ✏️ Edit Images: Modify existing images with text prompts

  • πŸ”„ Iterative Editing: Continue editing the last generated/edited image

  • πŸ–ΌοΈ Multiple Reference Images: Use reference images for style transfer and guidance

  • 🌍 Cross-Platform: Smart file paths for Windows, macOS, and Linux

  • πŸ”§ Easy Setup: Simple configuration with API key

  • πŸ“ Auto File Management: Automatic image saving with organized naming

Related MCP server: Gemini Image MCP

πŸ”‘ Setup

  1. Get your Gemini API key:

  2. Configure the MCP server: See configuration examples for your specific client below (Claude Code, Cursor, or other MCP clients).

πŸ’» Usage with Claude Code

Configuration:

Add this to your Claude Code MCP settings:

Option A: With environment variable (Recommended - Most Secure)

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["nano-banana-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Option B: Without environment variable

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["nano-banana-mcp"]
    }
  }
}

Usage Examples:

Generate an image of a sunset over mountains
Edit this image to add some birds in the sky
Continue editing to make it more dramatic

🎯 Usage with Cursor

Configuration:

Add to your Cursor MCP configuration:

Option A: With environment variable (Recommended)

{
  "nano-banana": {
    "command": "npx",
    "args": ["nano-banana-mcp"],
    "env": {
      "GEMINI_API_KEY": "your-gemini-api-key-here"
    }
  }
}

Option B: Without environment variable

{
  "nano-banana": {
    "command": "npx",
    "args": ["nano-banana-mcp"]
  }
}

Usage Examples:

  • Ask Cursor to generate images for your app

  • Create mockups and prototypes

  • Generate assets for your projects

πŸ”§ For Other MCP Clients

If you're using a different MCP client, you can configure nano-banana-mcp using any of these methods:

Configuration Methods

Method A: Environment Variable in MCP Config (Recommended)

{
  "nano-banana": {
    "command": "npx",
    "args": ["nano-banana-mcp"],
    "env": {
      "GEMINI_API_KEY": "your-gemini-api-key-here"
    }
  }
}

Method B: System Environment Variable

export GEMINI_API_KEY="your-gemini-api-key-here"
npx nano-banana-mcp

Method C: Using the Configure Tool

npx nano-banana-mcp
# The server will prompt you to configure when first used
# This creates a local .nano-banana-config.json file

πŸ› οΈ Available Commands

generate_image

Create a new image from a text prompt.

generate_image({
  prompt: "A futuristic city at night with neon lights"
})

edit_image

Edit a specific image file.

edit_image({
  imagePath: "/path/to/image.png",
  prompt: "Add a rainbow in the sky",
  referenceImages?: ["/path/to/reference.jpg"] // optional
})

continue_editing

Continue editing the last generated/edited image.

continue_editing({
  prompt: "Make it more colorful",
  referenceImages?: ["/path/to/style.jpg"] // optional
})

get_last_image_info

Get information about the last generated image.

get_last_image_info()

configure_gemini_token

Configure your Gemini API key.

configure_gemini_token({
  apiKey: "your-gemini-api-key"
})

get_configuration_status

Check if the API key is configured.

get_configuration_status()

βš™οΈ Configuration Priority

The MCP server loads your API key in the following priority order:

  1. πŸ₯‡ MCP Configuration Environment Variables (Highest Priority)

    • Set in your claude_desktop_config.json or MCP client config

    • Most secure as it's contained within the MCP configuration

    • Example: "env": { "GEMINI_API_KEY": "your-key" }

  2. πŸ₯ˆ System Environment Variables

    • Set in your shell/system environment

    • Example: export GEMINI_API_KEY="your-key"

  3. πŸ₯‰ Local Configuration File (Lowest Priority)

    • Created when using the configure_gemini_token tool

    • Stored as .nano-banana-config.json in current directory

    • Automatically ignored by Git and NPM

πŸ’‘ Recommendation: Use Method 1 (MCP config env variables) for the best security and convenience.

πŸ“ File Storage

Images are automatically saved to platform-appropriate locations:

  • Windows: %USERPROFILE%\\Documents\\nano-banana-images\\

  • macOS/Linux: ./generated_imgs/ (in current directory)

  • System directories: ~/nano-banana-images/ (when run from system paths)

File naming convention:

  • Generated images: generated-[timestamp]-[id].png

  • Edited images: edited-[timestamp]-[id].png

🎨 Example Workflows

Basic Image Generation

  1. generate_image - Create your base image

  2. continue_editing - Refine and improve

  3. continue_editing - Add final touches

Style Transfer

  1. generate_image - Create base content

  2. edit_image - Use reference images for style

  3. continue_editing - Fine-tune the result

Iterative Design

  1. generate_image - Start with a concept

  2. get_last_image_info - Check current state

  3. continue_editing - Make adjustments

  4. Repeat until satisfied

πŸ”§ Development

This project was created with Claude Code and follows these technologies:

  • TypeScript - Type-safe development

  • Node.js - Runtime environment

  • Zod - Schema validation

  • Google GenAI - Image generation API

  • MCP SDK - Model Context Protocol

Local Development

# Clone the repository
git clone https://github.com/claude-code/nano-banana-mcp.git
cd nano-banana-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

πŸ“‹ Requirements

  • Node.js 18.0.0 or higher

  • Gemini API key from Google AI Studio

  • Compatible with Claude Code, Cursor, and other MCP clients

🀝 Contributing

This project was generated by Claude Code, but contributions are welcome! Please feel free to:

  • Report bugs

  • Suggest new features

  • Submit pull requests

  • Improve documentation

πŸ“„ License

MIT License - see LICENSE file for details.

πŸ™ Acknowledgments

  • Claude Code - For generating this entire project

  • Google AI - For the powerful Gemini 2.5 Flash Image API

  • Anthropic - For the Model Context Protocol

  • Open Source Community - For the amazing tools and libraries

πŸ“ž Support


✨ Generated with love by Claude Code - The future of AI-powered development is here!

Available Tools

6 tools
configure_gemini_tokenA

Configure your Gemini API token for nano-banana image generation

ParametersJSON Schema
NameRequiredDescriptionDefault
apiKeyYesYour Gemini API key from Google AI Studio

TDQS

A3.5/5.0
Behavior2/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 merely says 'Configure your Gemini API token' without disclosing whether the token is stored persistently, overwrites existing configurations, or has any side effects. This is a significant gap for a mutation-like tool.

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, clear sentence with no unnecessary words. It is appropriately front-loaded with the verb and object.

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?

The tool is simple (1 param, no output schema), and the description states its purpose and domain. However, it lacks behavioral context such as persistence or success/failure indications, which matters given the absence of annotations. It is adequate but has clear gaps.

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?

The schema already provides a description for apiKey ('Your Gemini API key from Google AI Studio'), and the description adds only the term 'token', which is synonymous. With 100% schema coverage, there is no additional meaning added.

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 the specific verb 'configure' and identifies the resource 'Gemini API token', clearly distinguishing this from sibling tools like generate_image or get_configuration_status. It also connects to the domain of nano-banana image generation.

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 phrase 'for nano-banana image generation' implies this is a prerequisite for generation, but it does not explicitly state when to use it versus alternatives like get_configuration_status, nor does it mention exclusions. The usage is implied rather than explicit.

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

continue_editingA

Continue editing the LAST image that was generated or edited in this session, optionally using additional reference images. Use this for iterative improvements, modifications, or changes to the most recent image. This automatically uses the previous image without needing a file path.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesText describing the modifications/changes/improvements to make to the last image (e.g., 'change the hat color to red', 'remove the background', 'add flowers')
referenceImagesNoOptional array of file paths to additional reference images to use during editing (e.g., for style transfer, adding elements from other images, etc.)

TDQS

A4.4/5.0
Behavior4/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 effectively describes key behaviors: it operates on the last image in the session (stateful behavior), supports iterative editing, and can use reference images. However, it doesn't mention potential limitations like session persistence, error handling, or output format, leaving some gaps for a mutation tool.

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 front-loaded with the core purpose in the first sentence, followed by usage guidance and behavioral details in subsequent sentences. Every sentence adds value: the first defines the tool, the second specifies use cases, and the third explains the automatic image selection. There is no wasted text or redundancy.

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

Completeness4/5

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

Given no annotations and no output schema, the description does well by explaining the tool's purpose, usage, and key behavior (automatic use of last image). However, as a mutation tool with 2 parameters, it could benefit from more detail on output (e.g., what is returned) or error conditions, though the schema covers parameters adequately.

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 schema already fully documents both parameters (prompt and referenceImages). The description adds no additional parameter semantics beyond what's in the schema, such as examples or constraints not captured in the schema descriptions. This meets the baseline for high schema coverage.

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 specific action ('continue editing'), the resource ('the LAST image that was generated or edited in this session'), and distinguishes it from siblings by specifying it automatically uses the previous image without a file path, unlike edit_image which likely requires explicit image input. The verb+resource combination is precise and unambiguous.

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

Usage Guidelines5/5

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

The description explicitly states when to use this tool ('for iterative improvements, modifications, or changes to the most recent image') and provides a clear alternative context by mentioning it automatically uses the previous image, implying edit_image should be used for other images. It also distinguishes from generate_image by focusing on editing rather than creation.

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

edit_imageA

Edit a SPECIFIC existing image file, optionally using additional reference images. Use this when you have the exact file path of an image to modify.

ParametersJSON Schema
NameRequiredDescriptionDefault
imagePathYesFull file path to the main image file to edit
promptYesText describing the modifications to make to the existing image
referenceImagesNoOptional array of file paths to additional reference images to use during editing (e.g., for style transfer, adding elements, etc.)

TDQS

A3.9/5.0
Behavior3/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 mentions the tool edits existing files and uses reference images, but lacks details on permissions, side effects, error handling, or output format. For a mutation tool with zero annotation coverage, this is a moderate gap, though the core action is clear.

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 two concise sentences that are front-loaded with the main purpose and usage guideline. Every word earns its place, with no redundancy or fluff, making it highly efficient and easy to parse.

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 the tool's complexity (editing images with mutations), lack of annotations, and no output schema, the description is adequate but incomplete. It covers the basic purpose and usage but misses behavioral details like what the tool returns or potential side effects, leaving gaps for an AI agent to operate safely.

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 schema already documents all parameters thoroughly. The description adds minimal value beyond the schema, only implying that 'imagePath' must be exact and 'referenceImages' are optional for tasks like style transfer. Baseline 3 is appropriate as the schema does the heavy lifting.

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') and resource ('a SPECIFIC existing image file'), distinguishing it from sibling tools like 'generate_image' (creates new) and 'continue_editing' (continues previous edits). The specificity about modifying existing files is explicit and well-articulated.

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

Usage Guidelines4/5

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

The description provides clear context for when to use this tool ('when you have the exact file path of an image to modify'), which implicitly distinguishes it from 'generate_image' (for new images) and 'continue_editing' (for ongoing edits). However, it doesn't explicitly mention when NOT to use it or name alternatives, keeping it at a 4.

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

generate_imageA

Generate a NEW image from text prompt. Use this ONLY when creating a completely new image, not when modifying an existing one.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesText prompt describing the NEW image to create from scratch

TDQS

A4.1/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 full burden. It states this creates a 'NEW image' which implies a write/mutation operation, but doesn't disclose behavioral traits like authentication requirements, rate limits, output format, or error conditions. The description adds basic context about creating from scratch but lacks richer behavioral details.

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?

Two concise sentences with zero waste. The first sentence states the core purpose, the second provides crucial usage guidance. Every word earns its place, and the most important information is front-loaded.

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?

For a single-parameter tool with 100% schema coverage but no annotations and no output schema, the description provides adequate purpose and usage guidance. However, it lacks information about what the tool returns (no output schema) and doesn't address potential behavioral aspects like generation time, quality constraints, or failure modes that would be helpful for a generative tool.

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 schema already fully documents the single 'prompt' parameter. The description adds minimal value by reinforcing that the prompt should describe a 'NEW image to create from scratch', but this is essentially repeating what's in the schema description. Baseline 3 is appropriate when schema does the heavy lifting.

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 'Generate' and resource 'image', specifying it's 'from text prompt' and 'NEW'. It explicitly distinguishes from sibling tools by stating 'not when modifying an existing one', which contrasts with 'edit_image' in the sibling list.

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

Usage Guidelines5/5

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

The description provides explicit usage guidance: 'Use this ONLY when creating a completely new image, not when modifying an existing one.' This clearly defines when to use this tool versus the 'edit_image' sibling alternative, with a strong exclusion statement.

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

get_configuration_statusA

Check if Gemini API token is configured

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior2/5

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

With no annotations, the description carries the full burden. It says 'Check if...' which implies a read-only operation, but it does not disclose whether this is a local check, whether it makes network calls, or what happens if the token is missingβ€”leaving the agent uncertain about side effects and behavior.

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?

One short sentence of 8 words. It is appropriately minimal for a zero-argument status check, with no wasted words.

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 the tool's simplicity, the description states the core action, but it lacks details on the return value or the meaning of 'configured' (e.g., environment variable present vs. valid API key). Since there's no output schema, this information is missing.

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?

There are 0 parameters, and the schema already reflects that with 100% coverage. The description doesn't need to explain any parameters, so the baseline 4 applies.

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 ('Check'), names the resource ('Gemini API token'), and specifies the outcome ('is configured'). This clearly distinguishes it from siblings like configure_gemini_token (writes) and generate_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 gives no explicit guidance on when to use this tool versus alternatives. It's implied that it's a status check for token configuration, but there's no mention of prerequisites or context (e.g., 'use before generating images').

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

get_last_image_infoA

Get information about the last generated/edited image in this session (file path, size, etc.). Use this to check what image is currently available for continue_editing.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

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

With no annotations provided, the description must convey behavioral context. It explains that the tool returns metadata about the last session image and ties it to the editing workflow, but it does not disclose edge cases (e.g., no image yet) or any potential side effects, leaving the behavioral profile somewhat incomplete.

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 two concise sentences, with the primary purpose stated upfront and the usage guidance in the second sentence. No superfluous content.

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

Completeness4/5

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

For a simple, parameterless tool, the description gives a good overview of its purpose and output. It mentions the kind of information returned (file path, size) and the appropriate context (before continue_editing), though it stops short of specifying behavior when no image exists. Given the lack of an output schema, this is adequate but not exhaustive.

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?

The tool has zero parameters, and the schema is trivially complete (100% coverage). The description does not need to elaborate on parameters; it adds value by describing the output (file path, size, etc.), which satisfies the baseline for a parameterless tool.

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 ('Get') and resource ('information about the last generated/edited image'), clearly distinguishing this read-only info tool from the generation/editing siblings. It also specifies the scope ('in this session') and hints at the output content (file path, size).

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

Usage Guidelines4/5

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

The description explicitly states when to use the tool: to check what image is currently available for continue_editing. It provides a clear use case but does not enumerate alternative tools or exclusion criteria, so it falls short of full 5.

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.

  1. 6 tool updatesv1.0.3
    • First observedconfigure_gemini_token
    • First observedcontinue_editing
    • First observededit_image
    • First observedgenerate_image
    • First observedget_configuration_status
    • First observedget_last_image_info

TDQS

A3.8/5.0

Scored across 6 tools

Disambiguation5/5

Every tool has a clearly distinct purpose with no ambiguity. The descriptions explicitly differentiate between generating new images, editing specific files, continuing from the last image, and configuration tasks. The boundaries are well-defined, preventing misselection.

Naming Consistency4/5

The naming follows a consistent verb_noun pattern throughout (e.g., configure_gemini_token, generate_image, edit_image). The only minor deviation is 'continue_editing' which uses a verb_verb form, but it remains readable and fits the pattern overall.

Tool Count5/5

With 6 tools, the count is well-scoped for an image generation/editing server. Each tool earns its place by covering core operations like generation, editing, configuration, and session management without being excessive or sparse.

Completeness5/5

The tool set provides complete coverage for the image generation and editing domain. It includes CRUD-like operations (generate, edit, continue editing), configuration management, and status checks, with no obvious gaps that would cause agent failures in typical workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers