nano-banana-mcp


Nano Banana MCP server for generating and editing images with Google Gemini. No Gemini CLI required -- just an API key.

Quick Start

1. Get a Gemini API key from Google AI Studio

1. Add to your Claude Code settings (~/.claude/settings.json) or Claude Desktop config:

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "@daniel.barta/nano-banana-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

1. Restart Claude and ask it to generate an image.

Configuration

| Environment Variable | Required | Default | Description | |---------------------|----------|---------|-------------| | GEMINI_API_KEY | Yes | -- | Your Google AI API key | | GEMINI_MODEL | No | gemini-3.1-flash-image-preview | Gemini model for image generation/editing | | GEMINI_DESCRIBE_MODEL | No | gemini-2.5-flash | Gemini model for image description (text-only output) | | GEMINI_BASE_URL | No | -- | Custom base URL for Gemini API (proxy support) | | OUTPUT_DIR | No | ~/nano-banana-output | Directory for saved images |

Supported Models

| Model | Notes | |-------|-------| | gemini-3.1-flash-image-preview | Default. Latest, fastest | | gemini-3-pro-image-preview | Higher quality, slower | | gemini-2.5-flash-image | Fast, cost-effective |

Tools

generate_image

Generate an image from a text prompt. Supports batch generation (up to 4 images). Response contains a thumbnail preview; full-res image is saved to disk.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | prompt | string | Yes | Text description of the image | | aspectRatio | string | No | Aspect ratio (1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9) | | size | string | No | Image size (512px, 1K, 2K, 4K) | | n | number | No | Number of images to generate (1-4, default 1) | | negativePrompt | string | No | Things to exclude from the generated image | | systemInstruction | string | No | System instruction to guide the model |

edit_image

Edit an existing image based on a text instruction. Supports multi-image input (up to 10 images total). Response contains a thumbnail preview; full-res image is saved to disk.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | prompt | string | Yes | What to change | | filePath | string | Yes | Path to the source image | | additionalFilePaths | string[] | No | Additional image paths (up to 9) for multi-image editing | | aspectRatio | string | No | Aspect ratio (1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9) | | size | string | No | Image size (512px, 1K, 2K, 4K) | | negativePrompt | string | No | Things to exclude from the edited image | | systemInstruction | string | No | System instruction to guide the model |

describe_image

Get a text description of an image.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | filePath | string | Yes | Path to the image | | question | string | No | Specific question about the image | | systemInstruction | string | No | System instruction to guide the model |

Supported Input Formats

For edit_image and describe_image, the following image formats are supported:

JPEG, PNG, WebP, GIF, BMP, TIFF, SVG, HEIC/HEIF

File Path Resolution

When you provide a file path for editing or describing, the server searches for the file in this order:

1. Absolute path as given
2. Relative to the current working directory
3. Relative to the output directory
4. Basename only in the output directory

Thumbnails

To avoid hitting Claude Code's session file size limits, MCP responses contain thumbnail previews (max 512px, JPEG quality 80, ~20-50KB) instead of full-resolution images. Full-res images are always saved to disk at the path shown in the response metadata.

The first content block in generate/edit responses is a JSON metadata object: ``json { "model": "gemini-3.1-flash-image-preview", "count": 1, "images": [ { "filePath": "/Users/you/nano-banana-output/a-cat-1234567890.png", "mimeType": "image/png" } ] } ``

Development

git clone https://github.com/bartadaniel/nano-banana-mcp.git
cd nano-banana-mcp
npm install
npm run build

Use the local build in your config:

{
  "mcpServers": {
    "nano-banana": {
      "command": "node",
      "args": ["path/to/nano-banana-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Testing

npm test

Runs unit tests using Node.js built-in test runner (node:test). Tests cover error classes, all documented Gemini API response codes (BlockedReason, FinishReason), config shapes, image extraction edge cases, file operations, path security, and thumbnail generation.

License

MIT