@linche0859/nanobanana-mcp

v1.1.2

Published

12 days ago

Nano Banana MCP server for image generation with controllable output quality

0High
0Medium
0Low

linche0859

mcp gemini ai llm vision image-generation claude model-context-protocol

NanoBanana MCP

MCP server that brings Gemini's image generation and editing capabilities to Claude Desktop, Claude Code, and Cursor. Supports Nano Banana 2 (Flash) and Nano Banana Pro models.

This package is a fork of the upstream YCSE/nanobanana-mcp project and is maintained as a modified release by linche0859.
The npm package @linche0859/nanobanana-mcp is the release for this fork.
It is not the upstream official release from YCSE. This fork continues to be distributed under the MIT license.

Features

Image Generation - Create 1K, 2K, or 4K images from text prompts
Image Editing - Transform images with natural language instructions
Session Consistency - Maintain style/character across generations
Session Image Size - Set 1K, 2K, or 4K output per session
Runtime Model Switching - Switch between Flash and Pro models without restart
Multi-turn Chat - Conversational context with image support

Quick Start

Prerequisites

Node.js 18+
Google AI API Key (Get one here)

Installation Notes

This package is published to the npm registry:

@linche0859/nanobanana-mcp -> https://registry.npmjs.org/

If your local npm configuration maps the @linche0859 scope to GitHub Packages or another private registry, npx, npm install, and npm view may fail with 404, 401, or 403 errors even though the package exists on npmjs.

You can check your current scoped registry with:

npm config get @linche0859:registry

If needed, install or run the package with an explicit override:

npx -y @linche0859/nanobanana-mcp --@linche0859:registry=https://registry.npmjs.org/

Add to Claude Code

claude mcp add nanobanana-mcp -- npx -y @linche0859/nanobanana-mcp \
  -e "GOOGLE_AI_API_KEY=your_api_key"

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "nanobanana-mcp": {
      "command": "npx",
      "args": ["-y", "@linche0859/nanobanana-mcp"],
      "env": {
        "GOOGLE_AI_API_KEY": "your_api_key"
      }
    }
  }
}

Add to Cursor

Create or edit .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "nanobanana-mcp": {
      "command": "npx",
      "args": ["-y", "@linche0859/nanobanana-mcp"],
      "env": {
        "GOOGLE_AI_API_KEY": "your_api_key"
      }
    }
  }
}

See Cursor MCP Documentation for more details.

Tools

| Tool | Purpose | | ----------------------- | ------------------------------------------------------ | | set_aspect_ratio | Required. Set aspect ratio before image generation | | set_image_size | Set output image size to 1K, 2K, or 4K for the session | | set_model | Switch between flash/pro models at runtime | | gemini_generate_image | Generate images from text prompts | | gemini_edit_image | Edit images with natural language | | gemini_chat | Multi-turn conversation with images | | get_image_history | View session image history | | clear_conversation | Reset session context |

set_aspect_ratio (Required)

Must be called before generating or editing images.

Valid ratios: 1:1, 9:16, 16:9, 3:4, 4:3, 3:2, 2:3, 5:4, 4:5, 21:9

set_model

Switch models per-session without restarting:

| Value | Model | Description | | ------- | ------------------------------ | -------------------------------- | | flash | gemini-3.1-flash-image-preview | Nano Banana 2 - Faster (default) | | pro | gemini-3-pro-image-preview | Nano Banana Pro - Higher quality |

set_image_size

Set image output size per-session:

| Value | Description | | ----- | ----------------------------- | | 1K | Gemini API default image size | | 2K | Higher resolution output | | 4K | Maximum supported output size |

If not set, Gemini API defaults to 1K.

gemini_generate_image

{
  prompt: string;              // Image description
  image_size?: string;         // Optional: 1K, 2K, or 4K for this request
  aspect_ratio?: string;       // Override session ratio
  output_path?: string;        // Save path (default: ~/Documents/nanobanana_generated/)
  conversation_id?: string;    // Session ID
  use_image_history?: boolean; // Use previous images for consistency
  reference_images?: string[]; // Reference images for style
}

image_size takes priority over the current session image size set via set_image_size.

gemini_edit_image

{
  image_path: string;          // File path, "last", or "history:N"
  edit_prompt: string;         // Edit instructions
  image_size?: string;         // Optional: 1K, 2K, or 4K for this request
  aspect_ratio?: string;       // Override session ratio
  output_path?: string;        // Save path
  conversation_id?: string;    // Session ID
  reference_images?: string[]; // Style references
}

image_size takes priority over the current session image size set via set_image_size.

Slash Commands

Claude Code

npx @linche0859/nanobanana-mcp --install-commands claude-code
# Or manually:
# mkdir -p ~/.claude/commands
# cp commands/claude-code/*.md ~/.claude/commands/

Cursor

npx @linche0859/nanobanana-mcp --install-commands cursor
# Or manually:
# mkdir -p .cursor/commands
# cp commands/cursor/*.md .cursor/commands/

See Cursor Slash Commands for more details.

Available Commands

/nb-flash  - Switch to Flash model (faster)
/nb-pro    - Switch to Pro model (higher quality)

Usage Examples

Basic Generation

1. Set aspect ratio: set_aspect_ratio("16:9")
2. Optional: set image size: set_image_size("2K")
3. Generate: "A cyberpunk cityscape at sunset"

Character Consistency

// First image
{ prompt: "A red-hat cat", conversation_id: "cat" }

// Second image - same character
{ prompt: "The cat taking a nap", conversation_id: "cat", use_image_history: true }

Edit with History Reference

// Edit the last generated image
{ image_path: "last", edit_prompt: "Change hat to blue" }

// Edit specific image from history
{ image_path: "history:0", edit_prompt: "Add sunglasses" }

Switch Models Mid-Session

// Start with Flash for quick iterations
set_model({ model: "flash" })
{ prompt: "Draft concept art" }

// Switch to Pro for final render
set_model({ model: "pro" })
{ prompt: "Final polished version", use_image_history: true }

Configuration

Environment Variables

| Variable | Required | Description | | ------------------- | -------- | -------------------------------------------------------------------------------- | | GOOGLE_AI_API_KEY | Yes | Google AI API key | | NANOBANANA_MODEL | No | Default model (gemini-3.1-flash-image-preview or gemini-3-pro-image-preview) |

Image size is configured per session via set_image_size. If not set, Gemini defaults to 1K.

Output Location

Generated images save to ~/Documents/nanobanana_generated/:

Generated: generated_[timestamp].png
Edited: [original]_edited_[timestamp].png

Development

This repository contains the linche0859 fork. For the upstream source project, see YCSE/nanobanana-mcp.

git clone https://github.com/linche0859/nanobanana-mcp.git
cd nanobanana-mcp
npm install
npm run dev      # Development mode with hot reload
npm run build    # Production build
npm run start    # Run compiled server

Troubleshooting

Image generation fails:

Verify API key is valid
Check quota at Google AI Studio
Ensure set_aspect_ratio was called first

Package install or npx fails with 404, 401, or 403:

Check which registry npm uses for the @linche0859 scope: npm config get @linche0859:registry
If the result is https://npm.pkg.github.com/ or another non-npmjs registry, npm may be resolving this package from the wrong source
For a one-off run, use: npx -y @linche0859/nanobanana-mcp --@linche0859:registry=https://registry.npmjs.org/
For installs, use: npm install @linche0859/nanobanana-mcp --@linche0859:registry=https://registry.npmjs.org/
To make npmjs the default source for this scope on your machine, add this to your user-level .npmrc:

@linche0859:registry=https://registry.npmjs.org/

If you intentionally use GitHub Packages for other @linche0859/* packages, prefer setting a project-level .npmrc only where that alternate registry is actually required.

Tools not showing:

Restart Claude Desktop/Code
Check config file syntax
Verify npx -y @linche0859/nanobanana-mcp runs without errors

License

MIT