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 客户端集成使用。

安装和运行

# 通过 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 服务器:

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):

{
  "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 传输模式。

安装并运行

# 方式 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

或使用环境变量:

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

Claude Code CLI 配置 (HTTP 模式)

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:

{
  "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:

{
  "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

本地开发

# 克隆仓库
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

测试本地构建

# 链接到全局
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 for development guidelines.

License

MIT License - see LICENSE for details.

Made with ❤️ using Claude Code and PromptX architecture.