使用说明

MCP Banana Image

AI-Powered Image Generation MCP Server using Google Nano Banana 2 with custom endpoint

Features • Installation • Usage • Tools • Custom API Endpoint • Docker • Troubleshooting

概述

MCP香蕉图片 是一个模型上下文协议（MCP）服务器，它为您最喜欢的AI编码助手带来了AI驱动的图像生成功能。它采用谷歌的Nano Banana 2（gemini-3.1-flash-image）用于图像生成，gemini 3 flash用于文本增强，提供 16种专用工具 用于图像生成、编辑、分析和处理，所有这些都可以通过一个简单的自然语言界面完成。

亮点

16专用工具 -从简单的生成到高级风格的转换
自定义API端点支持 -与一起使用 Cliproxyapi 或其他Gemini API代理
智能提示增强 -自动优化提示以获得更好的结果
双重运输 -STDIO（默认）和HTTP（流式HTTP传输）
Docker就绪 -使用Docker部署为HTTP服务器

特性

类别	功能
生成	AI图像生成、徽标、图标、产品、社交媒体、UGC、信息图表、字符集
编辑	图像编辑、背景去除、图像混合、风格转换
分析	基于AI的图像分析，包括描述、alt文本、标签和OCR
处理	格式转换、调整大小、压缩
质量	2K/4K分辨率，10种宽高比，4种输出格式，智能压缩
一致性	字符一致性、风格转换、参考图像支持
整合	谷歌搜索基础、世界知识、平台特定优化

需求

Node.js 20+
Gemini API密钥 从谷歌人工智能工作室或 Cliproxyapi

安装

克劳德代码

claude mcp add mcp-banana-image \
  --env GEMINI_API_KEY=your_api_key \
  --env GEMINI_BASE_URL=https://generativelanguage.googleapis.com \
  --env IMAGE_OUTPUT_DIR=/path/to/output \
  --env SKIP_PROMPT_ENHANCEMENT=false \
  -- npx -y mcp-banana-image

添加 --scope user 全球安装。

光标

增添 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mcp-banana-image": {
      "command": "npx",
      "args": ["-y", "mcp-banana-image"],
      "env": {
        "GEMINI_API_KEY": "your_api_key",
        "GEMINI_BASE_URL": "https://generativelanguage.googleapis.com",
        "IMAGE_OUTPUT_DIR": "/path/to/output",
        "SKIP_PROMPT_ENHANCEMENT": "false"
      }
    }
  }
}

法典

增添 ~/.codex/config.toml:

[mcp_servers.mcp-banana-image]
command = "npx"
args = ["-y", "mcp-banana-image"]

[mcp_servers.mcp-banana-image.env]
GEMINI_API_KEY = "your_api_key"
GEMINI_BASE_URL = "https://generativelanguage.googleapis.com"
IMAGE_OUTPUT_DIR = "/path/to/output"
SKIP_PROMPT_ENHANCEMENT = "false"

开源代码

添加到您的 opencode.json 在您的项目根目录中或 ~/.config/opencode/config.json 对于全局配置：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp-banana-image": {
      "type": "local",
      "command": ["npx", "-y", "mcp-banana-image"],
      "enabled": true,
      "environment": {
        "GEMINI_API_KEY": "your_api_key",
        "GEMINI_BASE_URL": "https://generativelanguage.googleapis.com",
        "IMAGE_OUTPUT_DIR": "/path/to/output",
        "SKIP_PROMPT_ENHANCEMENT": "false"
      }
    }
  }
}

使用Cliproxy自定义端点：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp-banana-image": {
      "type": "local",
      "command": ["npx", "-y", "mcp-banana-image"],
      "enabled": true,
      "environment": {
        "GEMINI_API_KEY": "your_cliproxy_api_key",
        "GEMINI_BASE_URL": "https://yourdomain.com",
        "IMAGE_OUTPUT_DIR": "/path/to/output"
      }
    }
  }
}

要使用该工具，请添加 use mcp-banana-image 添加到您的提示中或将其添加到 AGENTS.md:

When you need to generate, edit, or analyze images, use `mcp-banana-image` tools.

自定义API终结点

MCP香蕉图像支持 自定义Gemini API端点，允许您使用其他API提供商，如 Cliproxy 或者您自己的代理服务器。

与Cliproxy一起使用

Cliproxy 是Gemini API代理服务，提供增强的可靠性、速率限制和附加功能。

配置示例（使用Cliproxy的Claude代码）

claude mcp add mcp-banana-image \
  --env GEMINI_API_KEY=your_cliproxy_api_key \
  --env GEMINI_BASE_URL=https://yourdomain.com \
  --env IMAGE_OUTPUT_DIR=/path/to/output \
  -- npx -y mcp-banana-image

配置示例（手动json）

{
  "mcpServers": {
    "mcp-banana-image": {
      "command": "npx",
      "args": ["-y", "mcp-banana-image"],
      "env": {
        "GEMINI_API_KEY": "your_cliproxy_api_key",
        "GEMINI_BASE_URL": "https://yourdomain.com",
        "IMAGE_OUTPUT_DIR": "/path/to/output"
      }
    }
  }
}

安全说明

生产：只允许HTTPS端点
发展：允许测试HTTP/localhost端点
端点URL在使用前经过验证，以防止SSRF攻击

工具参考

MCP香蕉图像提供 16种专用工具 按类别组织：

图像生成工具

工具	描述	主要功能
`generate_image`	从文本提示生成图像	自动提示增强、样式预设、纵横比
`generate_image_pro`	具有完全控制的高级生成	所有参数均已公开，参考图像，字符一致性
`generate_logo`	生成专业徽标	企业名称/标语，8种风格，透明背景，彩色品牌
`generate_icon`	生成图标、头像、贴纸	6种风格（平面、轮廓、3D），多种尺寸（16-512px）
`generate_product`	电子商务产品摄影	5种风格预设，平台合规性（亚马逊、Shopee、Tokopedia），6个类别
`generate_social_media`	平台优化的社交内容	9个平台，自动纵横比，文本安全区
`generate_ugc`	真实的用户生成内容	7个场景，10个设置，智能手机美学
`generate_infographic`	人工智能驱动的信息图表	4种风格、4种布局、品牌颜色、图标提示
`generate_character_set`	一致的角色系列	姿势、表情、5种艺术风格、角色表输出

图像编辑工具

工具	描述	主要功能
`edit_image`	使用自然语言编辑图像	添加/删除元素、更改背景、增强
`remove_background`	去除图像背景	透明PNG输出，AI驱动分割
`blend_images`	混合多幅图像	4种模式（无缝、拼贴、双重曝光、叠加），2-4幅图像
`style_transfer`	应用艺术风格	单次/多次引用，风格强度控制，元素保存

图像处理工具

工具	描述	主要功能
`convert_image`	格式转换	PNG、JPEG、WebP、AVIF、压缩预设
`resize_image`	调整图像大小	精确尺寸，5种贴合模式，保持外观

分析工具

工具	描述	主要功能
`analyze_image`	AI驱动的图像分析	描述、alt文本、标签、OCR、审核

用法示例

基本图像生成

"Generate a mountain landscape at sunset"

徽标生成

generate_logo businessName='TechStart' tagline='Innovation Made Simple' style='modern'

产品摄影

generate_product productDescription='handmade leather wallet' style='premium' platform='amazon'

社交媒体内容

generate_social_media content='summer sale announcement' platform='instagram-post'

用户生成内容

generate_ugc description='person enjoying morning coffee' scenario='lifestyle' setting='home'

字符集生成

generate_character_set characterDescription='friendly robot mascot' poses=['front', 'waving'] style='cartoon'

风格迁移

style_transfer referenceStyleImage='./van-gogh.jpg' contentDescription='mountain landscape' styleStrength=0.8

图像分析

analyze_image imagePath='/path/to/photo.jpg' analysisType='description'

背景移除

remove_background imagePath='/path/to/product.jpg'

图像混合

blend_images imagePaths=['./bg.jpg', './subject.png'] instruction='Place subject on background' blendMode='seamless'

信息图生成

generate_infographic content='5 steps to improve productivity: 1. Set goals...' style='corporate' layout='vertical'

图像缩放

resize_image inputPath='./photo.jpg' width=800 height=600 fit='cover'

环境变量

核心配置

变量	必填	默认	描述
`GEMINI_API_KEY`	是	-	Google AI或Cliproxy API密钥
`GEMINI_BASE_URL`	否	Google默认值	自定义API端点（例如Cliproxy）
`IMAGE_OUTPUT_DIR`	没有	`./output`	生成图像的输出目录
`SKIP_PROMPT_ENHANCEMENT`	没有	`false`	禁用自动提示优化

HTTP传输配置

变量	必填	默认	描述
`MCP_TRANSPORT`	没有	`stdio`	运输方式： `stdio` 或 `http`
`MCP_API_KEY`	是（http）	-	http身份验证的API密钥
`MCP_HTTP_PORT`	没有	`3000`	HTTP服务器端口
`MCP_HTTP_HOST`	没有	`0.0.0.0`	HTTP服务器绑定地址
`MCP_CORS_ORIGIN`	没有	`*`	CORS允许的来源
`MCP_HTTP_TIMEOUT`	没有	`300000`	HTTP请求超时（毫秒）

输出格式和压缩

支持格式

格式	描述	透明度	最适合
`png`	无损	是	图形、徽标、图标
`jpeg`	有损	无	照片，大图
`webp`	现代	是	网络优化
`avif`	最佳压缩	是	现代浏览器

压缩预设

预设	描述	用例
`lossless`	无质量损失	存档、源文件
`high`	损失最小	专业工作
`balanced`	质量/尺寸比好	一般用途
`maximum`	最小文件大小	Web优化

宽高比

1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9

Docker部署

构建并运行

docker build -t mcp-banana-image .
docker-compose up

docker-compose.yml

services:
  mcp-banana-image:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./output:/app/output
    environment:
      - GEMINI_API_KEY=${GEMINI_API_KEY}
      - GEMINI_BASE_URL=${GEMINI_BASE_URL}
      - MCP_API_KEY=${MCP_API_KEY}
      - MCP_TRANSPORT=http

健康检查

curl http://localhost:3000/health

答复：

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "sessions": 0
}

建筑

flowchart TB
    subgraph Client
        A[AI Assistant]
    end

    subgraph MCP Server
        B[Transport Layer]
        C[MCP Handler]
        D[Tool Registry]
        E[16 Specialized Tools]
        F[Image Processor]
        G[File Manager]
    end

    subgraph "AI Providers"
        H[Gemini API]
        I[Cliproxy API]
    end

    A -->|STDIO/HTTP| B
    B --> C
    C --> D
    D --> E
    E -->|API Calls| H
    E -->|API Calls| I
    E --> F
    F -->|Save| G
    G --> J[(Output)]

故障排除

找不到API密钥

验证 GEMINI_API_KEY 设置正确
对于Cliproxy：确保使用正确的Cliproxy API密钥
检查以下位置的关键权限谷歌人工智能工作室

自定义终结点连接失败

验证 GEMINI_BASE_URL 格式正确（包括协议的完整URL）
确保端点可以从您的网络访问
对于生产：只允许HTTPS端点

图像未保存

确保 IMAGE_OUTPUT_DIR 是一条绝对路径
检查目录写入权限
验证磁盘空间可用性

生成超时

高分辨率图像（4K）需要更长的时间
具有许多姿势/表情的角色集需要更长的时间
考虑增加 MCP_HTTP_TIMEOUT 用于HTTP模式
检查到API端点的网络连接

提示被安全过滤器屏蔽

重新表述您的提示，以避免潜在的敏感内容
人工智能可能会拒绝可能生成不恰当图像的提示

字符一致性问题

提供详细的角色描述
使用可用的参考图像
启用 maintainCharacterConsistency 选项

发展

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Lint and format
npm run check:all

许可证

麻省理工学院

贡献

我们欢迎捐款！请阅读我们的贡献指南了解如何提交更改的指南。

Made with ❤️ by Trigi Digital