# Nano Banana Pro MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that brings **Google Gemini 2.0 Flash** native image generation capabilities directly into Claude Code and other MCP-compatible AI assistants.

Generate, edit, and compose images using natural language - all without leaving your coding environment.

## Features

- **Generate Images**: Create high-quality images from text prompts (up to 4K resolution)
- **Edit Images**: Modify existing images with text instructions
- **Continue Editing**: Iteratively refine the last generated image
- **Compose Images**: Combine up to 14 reference images into new compositions
- **Google Search Grounding**: Generate images based on real-time information
- **Multiple Aspect Ratios**: Support for 1:1, 16:9, 9:16, 4:3, 3:4, and more
- **High Resolution**: Output at 1K, 2K, or 4K resolution

## Prerequisites

- Docker Desktop installed and running
- Gemini API key from [Google AI Studio](https://aistudio.google.com/apikey)

## Quick Start

### 1. Build the Docker Image

```bash
cd nano-banana-pro-mcp
docker build -t nano-banana-pro-mcp .
```

### 2. Create Output Directory

```bash
mkdir -p output input
```

### 3. Add to Claude Code

Add the MCP server to Claude Code using one of these methods:

#### Option A: Using claude mcp add (Recommended)

```bash
claude mcp add nano-banana-pro \
  --transport stdio \
  -- docker run -i --rm \
    -e GEMINI_API_KEY=$GEMINI_API_KEY \
    -v $(pwd)/output:/output \
    -v $(pwd)/input:/input:ro \
    nano-banana-pro-mcp
```

#### Option B: Manual Configuration

Add to your Claude Code MCP configuration file (`~/.claude/claude_desktop_config.json` or similar):

```json
{
  "mcpServers": {
    "nano-banana-pro": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GEMINI_API_KEY",
        "-v", "/path/to/output:/output",
        "-v", "/path/to/input:/input:ro",
        "nano-banana-pro-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Available Tools

### `generate_image`
Generate a new image from a text prompt.

**Parameters:**
- `prompt` (required): Text description of the image to create
- `aspectRatio` (optional): 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
- `resolution` (optional): 1K, 2K, or 4K
- `useGoogleSearch` (optional): Enable real-time information grounding

**Example:**
```
Generate a professional hero image for a tech startup website, showing a
modern office with developers collaborating, 16:9 aspect ratio, 2K resolution
```

### `edit_image`
Edit an existing image with text instructions.

**Parameters:**
- `imagePath` (required): Path to the image file
- `prompt` (required): Description of the modifications
- `referenceImages` (optional): Array of reference image paths
- `aspectRatio` (optional): Output aspect ratio
- `resolution` (optional): Output resolution

**Example:**
```
Edit /input/logo.png - Change the background color to gradient blue and
add a subtle glow effect around the text
```

### `continue_editing`
Continue editing the last generated/edited image.

**Parameters:**
- `prompt` (required): Description of additional modifications
- `referenceImages` (optional): Reference images for style transfer, etc.
- `aspectRatio` (optional): Output aspect ratio
- `resolution` (optional): Output resolution

**Example:**
```
Make the colors more vibrant and add a subtle drop shadow
```

### `compose_images`
Combine multiple images into a new composition.

**Parameters:**
- `images` (required): Array of image paths (up to 14)
- `prompt` (required): How to combine the images
- `aspectRatio` (optional): Output aspect ratio
- `resolution` (optional): Output resolution

**Example:**
```
Compose these product photos into a professional catalog layout
with consistent lighting and white background
```

### `get_last_image_info`
Get information about the last generated image.

### `get_configuration_status`
Check if the API key is configured.

## Tips for Best Results

1. **Be Descriptive**: The more detail in your prompt, the better the result
2. **Use Photography Terms**: For realistic images, mention camera angles, lens types, lighting
3. **Iterate**: Use `continue_editing` to refine images step by step
4. **Reference Images**: Use up to 14 reference images for character consistency or style transfer
5. **Google Search**: Enable for real-time data like weather, news, or current events

## Output Location

Generated images are saved to the `/output` directory (mounted from `./output` on your host).

## Troubleshooting

### "GEMINI_API_KEY not set"
Make sure your API key is set in your environment:
```bash
export GEMINI_API_KEY="your-key-here"
```

### Images not appearing
Check the `./output` directory on your host machine. Ensure the volume mount is correct.

### Docker permission issues
On Linux, you may need to run:
```bash
sudo chown -R $USER:$USER output
```

## Development

To run locally without Docker:

```bash
npm install
npm run build
GEMINI_API_KEY=your-key OUTPUT_DIR=./output npm start
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT

## Acknowledgments

- [Google Gemini](https://deepmind.google/technologies/gemini/) for the image generation API
- [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic
- [Claude Code](https://claude.ai/code) for the amazing AI coding assistant