npm package: @igorstechnoclub/mcp-nano-banana
Description: MCP server for Google Nano Banana (Gemini) image generation
Author: igorstechnoclub
Latest version: 1.2.0

# mcp-nano-banana

MCP server for AI-powered image generation using Google Gemini models. Generate images from text prompts or combine multiple reference images.

## Features

- Text-to-image generation
- Multi-image combination (up to 14 reference images)
- Automatic fallback from Pro to Flash model on rate limits
- Save output to file or return inline
- Support for multiple aspect ratios and output formats
- Generate a full favicon package (PNG sizes, favicon.ico, manifest, README, optional ZIP)

## Use Cases

- **Generate illustrations** - Create images for blog posts, documentation, or presentations
- **Edit existing images** - Add objects, change backgrounds, or modify elements in photos
- **Combine multiple images** - Merge product photos, create composites, or blend styles
- **Create variations** - Generate different versions of a concept or design
- **Prototype UI mockups** - Quickly visualize interface ideas or app screens
- **Generate icons and assets** - Create logos, buttons, or graphic elements for projects

## Installation

```bash
npm install -g @igorstechnoclub/mcp-nano-banana
```

**Important:** Don't forget to set your `GEMINI_API_KEY` environment variable (see Configuration below).

## Configuration

### Environment Variable

Set your Gemini API key:

```bash
export GEMINI_API_KEY=your-api-key
```

Get an API key at: https://aistudio.google.com/apikey

### Claude Code Setup

Add the MCP server using the CLI:

```bash
claude mcp add nano-banana -e GEMINI_API_KEY=your-api-key -- npx -y @igorstechnoclub/mcp-nano-banana@latest
```

Or add manually to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "@igorstechnoclub/mcp-nano-banana@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Usage

### Tool: `generate_image`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Text description or editing instructions |
| `imagePaths` | string[] | No | - | Reference image paths (up to 14) |
| `model` | string | No | `gemini-3-pro-image-preview` | Model to use |
| `aspectRatio` | string | No | `1:1` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4` |
| `outputFormat` | string | No | `png` | `png`, `jpeg`, `webp` |
| `outputPath` | string | No | - | Save image to this path |

### Examples

**Generate from text:**
```
prompt: "A sunset over mountains"
outputPath: "/path/to/output.png"
```

**Combine images:**
```
prompt: "Put these glasses on this person's face"
imagePaths: ["/path/to/face.jpg", "/path/to/glasses.jpg"]
outputPath: "/path/to/result.png"
```

### Tool: `generate_favicons`

Generate a complete favicon package from a prompt or an existing image.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | No* | - | Icon description (required if `imagePath` not provided) |
| `imagePath` | string | No* | - | Path to existing master icon image |
| `model` | string | No | `gemini-3-pro-image-preview` | Model to use when generating from prompt |
| `outputDir` | string | No | - | Directory to write individual favicon files |
| `outputPath` | string | No | - | Save ZIP package to this path |
| `returnZipBase64` | boolean | No | `false` | Return ZIP as base64 text |
| `appName` | string | No | `My App` | Manifest `name` |
| `shortName` | string | No | `App` | Manifest `short_name` |
| `themeColor` | string | No | `#ffffff` | Manifest theme color |
| `backgroundColor` | string | No | `#ffffff` | Manifest background color |
| `includeReadme` | boolean | No | `true` | Include `README.md` in the package |

**Generate from prompt and write files + ZIP:**
```
prompt: "A minimalist banana icon with a soft gradient"
outputDir: "/path/to/favicon"
outputPath: "/path/to/favicon.zip"
```

**Use an existing image and return base64 ZIP:**
```
imagePath: "/path/to/master-icon.png"
returnZipBase64: true
```

### Codex MCP Usage (Local)

**Build the local server:**
```bash
npm install
npm run build
```

**Register with Codex:**
```bash
codex mcp add nano-banana --env GEMINI_API_KEY=your-api-key -- node /path/to/mcp-nano-banana/dist/index.js
```

**Example request:**
```
Use MCP tool generate_favicons with:
prompt: "A bold, simple icon for VideoFix: a stylized play button combined with a small wrench, flat design, high contrast, centered on a soft off-white background."
appName: "VideoFix"
shortName: "VideoFix"
themeColor: "#1d1b18"
backgroundColor: "#f7f3ef"
outputDir: "/path/to/project/assets/favicon"
```

## Models

- `gemini-3-pro-image-preview` - High quality (default)
- `gemini-2.5-flash-image` - Fast generation

The server automatically falls back to Flash if Pro hits rate limits (429/403/402 errors).

## Development

```bash
# Build
npm run build

# Test
npm test

# Run directly
node dist/index.js
```

## Blog Post

Read about the development of this project: https://igorstechnoclub.com/mcp-nano-banana/

## Author

Visit my personal site: https://igorstechnoclub.com

## License

MIT