# Nano Banana MCP Server 🍌🤖

A professional MCP (Model Context Protocol) Server for generating and editing images with Google Gemini AI. Built with PromptX architecture for robust image generation, editing, and composition workflows.

## Features

🎨 **Image Generation from Text**: Create stunning images from detailed text descriptions
✏️ **Image Editing with Text**: Modify existing images using natural language instructions
🎯 **Image Composition**: Combine multiple images into new compositions
⚡ **High Performance**: Built with TypeScript and optimized for speed
🔒 **Secure**: Sandboxed execution environment with proper error handling

## Quick Start

### 方式 1: Stdio 传输 (推荐)

这是最简单也是推荐的使用方式,适合与 Claude Code CLI 等 MCP 客户端集成使用。

#### 安装和运行

```bash
# 通过 npx 直接运行 (无需安装)
npx -y @ansonzeng/nano-banana-mcp-server

# 或者使用简短命令名
npx -y @ansonzeng/nano-banana-mcp-server nano-banana-mcp
```

#### Claude Code CLI 配置

在 Claude Code CLI 中添加 MCP 服务器:

```bash
claude mcp add --scope user nano-banana '{
  "command": "npx",
  "args": ["-y", "@ansonzeng/nano-banana-mcp-server"],
  "env": {
    "GEMINI_BASE_URL": "https://your-api-provider.com",
    "GEMINI_API_KEY": "your_api_key_here",
    "IMAGE_OUTPUT_DIR": "/path/to/your/output/folder"
  }
}'
```

或者直接编辑配置文件 (`~/.claude/mcp.json`):

```json
{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "@ansonzeng/nano-banana-mcp-server"],
      "env": {
        "GEMINI_BASE_URL": "https://your-api-provider.com",
        "GEMINI_API_KEY": "your_api_key_here",
        "IMAGE_OUTPUT_DIR": "/path/to/your/output/folder"
      }
    }
  }
}
```

### 方式 2: HTTP 传输 (可选)

如果你需要将服务器部署为独立的 HTTP 服务,可以使用 HTTP 传输模式。

#### 安装并运行

```bash
# 方式 1: 通过 npx 运行 HTTP 模式
npx -y @ansonzeng/nano-banana-mcp-server nano-banana-mcp-http

# 方式 2: 全局安装后运行
npm install -g @ansonzeng/nano-banana-mcp-server
nano-banana-mcp-http
```

或使用环境变量:

```bash
PORT=3000 HOST=localhost nano-banana-mcp-http
```

#### Claude Code CLI 配置 (HTTP 模式)

```bash
claude mcp add --scope user --transport http nano-banana http://localhost:8080/mcp
```

### 环境变量说明

- `GEMINI_API_KEY`: 你的 API 供应商提供的 API 密钥 (必填)
- `GEMINI_BASE_URL`: 你的 API 供应商的基础 URL (必填)
- `GEMINI_MODEL_NAME`: 模型名称 (可选,默认: gemini-2.5-flash-image-preview)
- `IMAGE_OUTPUT_DIR`: 图片输出目录 (可选,默认: ./outputs)
- `PORT`: HTTP 服务器端口 (仅 HTTP 模式,默认: 8080)
- `HOST`: HTTP 服务器监听地址 (仅 HTTP 模式,默认: 0.0.0.0)

## Available Tools

### 1. `createImageFromText`
Generate images from text descriptions.

**Parameters:**
- `prompt` (string): Detailed description of the image you want to generate

**Example:**
```json
{
  "prompt": "A cat wearing an astronaut helmet, cartoon style"
}
```

### 2. `editImageWithText`
Edit existing images with text instructions.

**Parameters:**
- `prompt` (string): What modifications you want to make
- `inputImage` (string): Image file path or Base64 data

**Example:**
```json
{
  "prompt": "Add a party hat to this cat",
  "inputImage": "/path/to/image.jpg"
}
```

### 3. `compositeImagesWithText`
Combine multiple images into new compositions.

**Parameters:**
- `prompt` (string): How you want to combine the images
- `inputImages` (array): Array of Base64 image data

## Development

### 本地开发

```bash
# 克隆仓库
git clone https://github.com/yourusername/nano-banana-mcp-server.git
cd nano-banana-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# 运行 Stdio 模式 (默认)
npm start

# 或运行 HTTP 模式
npm run start:http
```

### 测试本地构建

```bash
# 链接到全局
npm link

# 在其他项目中使用
nano-banana-mcp-server  # Stdio 模式 (默认)
nano-banana-mcp         # Stdio 模式 (简短名)
nano-banana-mcp-http    # HTTP 模式
```

## File Output

Generated and edited images are saved to an `outputs/` directory in your current working directory with timestamps to prevent overwrites.

## Technical Details

- **Built with**: TypeScript, Node.js 18+
- **Architecture**: PromptX-based modular design
- **Protocol**: Model Context Protocol (MCP)
- **AI Provider**: Google Gemini AI
- **Output Format**: PNG images with Base64 encoding

## Error Handling

The server includes comprehensive error handling for:
- Invalid API keys or network issues
- File reading/writing permissions
- Image format validation
- API response parsing

## Requirements

- Node.js 18.0.0 or higher
- Valid Google Gemini API key
- Network access to API provider

## Contributing

This project follows the PromptX architecture principles. See [CLAUDE.md](./CLAUDE.md) for development guidelines.

## License

MIT License - see [LICENSE](./LICENSE) for details.

---

Made with ❤️ using Claude Code and PromptX architecture.