Nano-Banana MCP Server
Provides AI image generation and editing capabilities using Google's Gemini 2.5 Flash Image API, enabling users to generate images from text, modify existing images with prompts, and perform iterative editing with reference image support.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Nano-Banana MCP Servergenerate a futuristic city skyline with neon lights"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Get your Gemini API key:
Visit Google AI Studio
Create a new API key
Copy it for configuration
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 mountainsEdit this image to add some birds in the skyContinue 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-mcpMethod 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:
π₯ MCP Configuration Environment Variables (Highest Priority)
Set in your
claude_desktop_config.jsonor MCP client configMost secure as it's contained within the MCP configuration
Example:
"env": { "GEMINI_API_KEY": "your-key" }
π₯ System Environment Variables
Set in your shell/system environment
Example:
export GEMINI_API_KEY="your-key"
π₯ Local Configuration File (Lowest Priority)
Created when using the
configure_gemini_tokentoolStored as
.nano-banana-config.jsonin current directoryAutomatically 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].pngEdited images:
edited-[timestamp]-[id].png
π¨ Example Workflows
Basic Image Generation
generate_image- Create your base imagecontinue_editing- Refine and improvecontinue_editing- Add final touches
Style Transfer
generate_image- Create base contentedit_image- Use reference images for stylecontinue_editing- Fine-tune the result
Iterative Design
generate_image- Start with a conceptget_last_image_info- Check current statecontinue_editing- Make adjustmentsRepeat 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
π Issues: GitHub Issues
π Documentation: This README and inline code comments
π¬ Discussions: GitHub Discussions
β¨ Generated with love by Claude Code - The future of AI-powered development is here!
Available Tools
6 toolsconfigure_gemini_tokenA
Configure your Gemini API token for nano-banana image generation
| Name | Required | Description | Default |
|---|---|---|---|
| apiKey | Yes | Your Gemini API key from Google AI Studio |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Text describing the modifications/changes/improvements to make to the last image (e.g., 'change the hat color to red', 'remove the background', 'add flowers') | |
| referenceImages | No | Optional array of file paths to additional reference images to use during editing (e.g., for style transfer, adding elements from other images, etc.) |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| imagePath | Yes | Full file path to the main image file to edit | |
| prompt | Yes | Text describing the modifications to make to the existing image | |
| referenceImages | No | Optional array of file paths to additional reference images to use during editing (e.g., for style transfer, adding elements, etc.) |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Text prompt describing the NEW image to create from scratch |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
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.
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.
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.
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.
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.
6 tool updates
v1.0.3- First observed
configure_gemini_token - First observed
continue_editing - First observed
edit_image - First observed
generate_image - First observed
get_configuration_status - First observed
get_last_image_info
TDQS
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for Qwen Image 3 AI image generation
MCP server for NanoBanana AI image generation and editing
MCP server for Flux AI image generation
Generate AI images, video, music, and sound effects, and upscale them, from any MCP client.
Related MCP Servers
- AlicenseBqualityBmaintenanceA MCP server that provides AI-powered image generation capabilities through Google's Gemini 2.5 Flash Image model.4399MIT
- FlicenseAqualityDmaintenanceAn MCP server that enables AI image generation, editing, and analysis using Google's Gemini 3.0 models. It supports high-resolution outputs up to 4K, style transfers, and multi-image mixing through specialized tools.3-
- AlicenseBqualityBmaintenanceAn MCP server for AI-powered image generation, editing, analysis, and transformation using Google's Gemini and Imagen 4 models.192AGPL 3.0
- AlicenseAqualityDmaintenanceMCP server for generating and editing images using Google Gemini API, with support for multi-turn iterative refinement.325 npmMIT