@laomeifun/gemini-images

v0.3.6

Published

17 days ago

MCP server: generate and edit images via Gemini with Nano Banana multi-turn conversation support

0High
0Medium
0Low

laomeifun

mcp model-context-protocol gemini image-generation image-editing nano-banana multi-turn ai openai-compatible

@laomeifun/gemini-images

一个基于 MCP (Model Context Protocol) 的图片生成工具，通过 OpenAI-compatible 接口调用 Gemini 图片模型生成图片。支持 Claude Desktop、VS Code Copilot 等 MCP 客户端。

✨ 特性

🎨 AI 图片生成：通过自然语言描述生成图片
📁 自动保存：图片自动保存到指定目录
🖼️ Markdown 展示：返回 Markdown 图片语法，支持直接预览
🔧 灵活配置：支持多种环境变量配置
🌍 跨平台：支持 Windows、macOS、Linux
📦 即装即用：通过 npx 直接运行，无需手动安装

🚀 快速开始

方式一：使用 npx（推荐）

在 MCP 客户端配置中直接使用：

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "@laomeifun/gemini-images"],
      "env": {
        "OPENAI_BASE_URL": "http://127.0.0.1:8317",
        "OPENAI_API_KEY": "<YOUR_API_KEY>",
        "OPENAI_MODEL": "gemini-3-pro-image-preview"
      }
    }
  }
}

方式二：全局安装

npm install -g @laomeifun/gemini-images

然后在 MCP 配置中使用：

{
  "mcpServers": {
    "gemini-image": {
      "command": "gemini-images",
      "env": {
        "OPENAI_BASE_URL": "http://127.0.0.1:8317",
        "OPENAI_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

方式三：从源码运行

git clone https://github.com/laomeifun/gemini-images.git
cd gemini-images
npm install

MCP 配置：

{
  "mcpServers": {
    "gemini-image": {
      "command": "node",
      "args": ["<PATH_TO>/gemini-images/src/index.js"],
      "env": {
        "OPENAI_BASE_URL": "http://127.0.0.1:8317",
        "OPENAI_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

⚙️ 环境变量

| 变量名 | 必填 | 默认值 | 说明 | |--------|------|--------|------| | OPENAI_BASE_URL | 否 | http://127.0.0.1:8317 | OpenAI-compatible API 地址 | | OPENAI_API_KEY | 视情况 | - | API Key（如果你的网关需要鉴权） | | OPENAI_MODEL | 否 | gemini-3-pro-image-preview | 使用的模型名称 | | OPENAI_IMAGE_SIZE | 否 | 1024x1024 | 默认图片尺寸 | | OPENAI_IMAGE_MODE | 否 | chat | API 模式：chat、images、auto | | OPENAI_IMAGE_OUT_DIR | 否 | - | 默认保存目录（如果工具调用时未指定） | | OPENAI_IMAGE_RETURN | 否 | path | 默认返回格式：path（保存文件）或 image（只返回 base64） | | OPENAI_IMAGE_INLINE_MAX_SIZE | 否 | 524288 (512KB) | 内联展示的最大图片大小（字节），超过则只返回路径 | | OPENAI_TIMEOUT_MS | 否 | 120000 | 请求超时时间（毫秒） | | SESSION_TTL_MS | 否 | 1800000 (30分钟) | 多轮对话会话过期时间（毫秒） | | OPENAI_DEBUG | 否 | - | 设为 1 开启调试日志 |

🛠️ 工具参数

`generate_image`

生成或编辑 AI 图片的 MCP 工具，支持 Nano Banana 多轮对话。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | prompt | string / string[] | ✅ | 图片描述，越详细效果越好。编辑时描述要修改的内容 | | session_id | string | 否 | 会话 ID。传入之前返回的 session_id 可继续多轮对话编辑 | | image | string | 否 | 输入图片（base64 或 data URL）。传入后将基于此图片进行编辑 | | outDir | string | 否 | 保存目录。支持绝对路径、相对路径、~ 开头的用户目录。未指定时默认保存到用户图片目录（Windows/macOS: ~/Pictures，Linux: XDG_PICTURES_DIR） | | size | string / number | 否 | 图片尺寸，默认 1024x1024。可选：512x512、1024x1792（竖版）、1792x1024（横版） | | n | number | 否 | 生成数量，默认 1，最多 4 | | output | string | 否 | 返回格式：path（默认，保存文件）或 image（只返回数据不保存） |

注：当 output=image 时，图片不会保存到本地，仅返回 base64 数据。

🍌 Nano Banana 多轮对话

本工具支持类似 Google Nano Banana 的多轮对话图片编辑功能，可以在对话中持续迭代修改图片。

工作原理

┌─────────────────────────────────────────────────────────────┐
│  第一次调用                                                   │
│  generate_image(prompt: "画一只橙色的猫")                     │
│  → 生成图片，返回 session_id: "abc123"                        │
├─────────────────────────────────────────────────────────────┤
│  第二次调用                                                   │
│  generate_image(prompt: "把背景改成蓝天白云",                  │
│                 session_id: "abc123")                        │
│  → 基于上一张图片进行编辑                                      │
├─────────────────────────────────────────────────────────────┤
│  第三次调用                                                   │
│  generate_image(prompt: "在猫旁边加一只小狗",                  │
│                 session_id: "abc123")                        │
│  → 继续在同一会话中编辑                                        │
└─────────────────────────────────────────────────────────────┘

使用示例

首次生成：

用户：画一只橙色的猫咪坐在窗台上

AI 调用工具后返回：

✅ 成功生成 1 张图片
🔗 session_id: `a1b2c3d4`
💡 提示：后续调用时传入此 session_id 可继续编辑这张图片

继续编辑：

用户：把背景改成星空

AI 自动传入 session_id 继续编辑同一张图片。

直接编辑指定图片

也可以传入 image 参数直接编辑任意图片：

{
  "prompt": "把这张图片改成水彩画风格",
  "image": "data:image/png;base64,..."
}

使用示例

在 Claude 或其他 MCP 客户端中：

画一只橙色的猫咪坐在窗台上，阳光透过窗户照进来，水彩画风格

AI 会自动调用工具：

{
  "prompt": "一只橙色的猫咪坐在窗台上，阳光透过窗户照进来，水彩画风格",
  "outDir": "~/Pictures/ai-generated",
  "size": "1024x1024"
}

返回格式

✅ 成功生成 1 张图片：

![image-20260104-123456-abc1.png](file:///C:/Users/xxx/Pictures/ai-generated/image-20260104-123456-abc1.png)
📁 C:/Users/xxx/Pictures/ai-generated/image-20260104-123456-abc1.png

🔧 本地调试

# 复制环境变量配置
cp .env.example .env
# 编辑 .env 填入你的配置

# 测试上游 API 连通性
npm run debug:upstream -- --prompt "A cute cat" --size 1024x1024

# 测试 MCP 工具调用
npm run debug:mcp -- --prompt "A cute cat" --out ~/Pictures

📝 配置文件位置

Claude Desktop (Windows)：%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop (macOS)：~/Library/Application Support/Claude/claude_desktop_config.json
VS Code Copilot：参考 VS Code MCP 扩展文档

🤝 兼容性

Node.js：>= 18
MCP 客户端：Claude Desktop、VS Code Copilot、其他支持 MCP 的客户端
API 后端：任何 OpenAI-compatible 的图片生成 API

📄 License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@laomeifun/gemini-images

✨ 特性

🚀 快速开始

方式一：使用 npx（推荐）

方式二：全局安装

方式三：从源码运行

⚙️ 环境变量

🛠️ 工具参数

generate_image

🍌 Nano Banana 多轮对话

工作原理

使用示例

直接编辑指定图片

使用示例

返回格式

🔧 本地调试

📝 配置文件位置

🤝 兼容性

📄 License

`generate_image`