Gemini Image MCP Server

🚀 Gemini Image MCP Server

这是一个使用谷歌Gemini AI进行图像生成和编辑的模型上下文协议（MCP）服务器。它支持使用可选的上下文图像来引导生成结果，并且现在包含了专门的编辑工作流程。默认情况下，该服务器针对创建引人注目的方形（1:1）社交媒体图像进行了优化。

✨ 主要特性

• ✨ 使用谷歌Gemini AI进行图像生成
• 🎨 支持多种宽高比（1:1、16:9、9:16、4:3、3:4）
• 📱 默认针对1:1格式的社交媒体进行优化
• 🎯 支持自定义风格
• 🧩 可使用上下文图像引导生成
• ✏️ 提供专门的编辑工具，无需额外操作即可修改现有图像
• 🏷️ 支持水印 - 可在生成的结果上叠加水印图像
• 💾 自动将图像保存到本地文件
• 📁 支持灵活配置输出路径
• 🛡️ 可自定义安全设置

📦 安装指南

1. 克隆此仓库
2. 安装依赖：

npm install

3. 构建项目：

npm run build

📚 详细文档

环境变量

你需要配置谷歌AI的API密钥：

export GOOGLE_API_KEY="your-api-key-here"

获取谷歌AI API密钥

1. 访问 Google AI Studio
2. 创建一个新的API密钥
3. 复制密钥并将其设置为环境变量

客户端配置

{
  "servers": {
    "gemini-image": {
      "command": "node",
      "args": ["/full/path/to/project/dist/index.js"],
      "env": {
        "GOOGLE_API_KEY": "your-api-key-here"
      }
    }
  }
}

💻 使用示例

可用工具

generate_image

根据文本描述创建全新的图像，可选择使用一个或多个图像作为视觉上下文。当你想生成全新内容时，请使用此工具。

参数：

• description（字符串，必填）：所需图像的详细描述。
• images（字符串数组，可选）：用作上下文的图像路径数组（绝对或相对路径）。用于“编辑”或引导风格/内容。
• aspectRatio（字符串，可选）：方向预设（square、landscape、portrait）。默认值：square。
• style（字符串，可选）：额外的风格（例如，“minimalist”、“colorful”、“professional”、“artistic”）。
• outputPath（字符串，可选）：图像保存的位置。如果省略，则保存到当前目录。
• watermarkPath（字符串，可选）：要叠加的水印图像的路径。
• watermarkPosition（字符串，可选）：水印位置，可选值为 top-left、top-right、bottom-left、bottom-right。默认值：bottom-right。

使用示例：

# 基础用法 - 保存到当前目录
Generate an image of a mountain landscape at sunset with warm, minimalist style

# 使用上下文图像引导构图
Generate an image: "Create a futuristic city skyline inspired by this photo", images: ["./reference-skyline.jpg"], aspectRatio: "landscape"

# 使用多个上下文图像
Generate an image combining style of a logo and a photo, images: ["./photo.jpg", "./logo.png"], style: "professional"

当你请求特定的方向（square、landscape 或 portrait）时，服务器会自动添加一个不可见的辅助图像（assets/square.png、assets/landscape.png 或 assets/portrait.png），以便Gemini遵循目标尺寸。

edit_image

使用聚焦的文本指令修改现有图像。除非你明确要求进行结构更改，否则此工具将保留原始图像的框架。

参数：

• description（字符串，必填）：描述要应用于提供的图像的编辑指令。
• image（字符串，必填）：要编辑的图像文件的路径（绝对或相对路径）。
• outputPath（字符串，可选）：保存编辑结果的位置。如果省略，服务器将使用工作目录并自动生成文件名。

使用示例：

# 简单编辑
Edit image: "Soften skin tones and remove flyaway hairs", image: "./headshot.png"

# 深度修饰
Edit image: "Turn the product label red and add subtle sparkle highlights", image: "./product-shot.jpg"

# 自定义路径和水印（左上角）
Generate an image of a space cat, outputPath: "./images/epic_pizza.png", watermarkPath: "./my_logo.png", watermarkPosition: "top-left"

水印功能

generate_image 工具支持为图像添加水印：

特性：

• 🏷️ 可在任何生成的输出中添加图像水印
• 📍 可在任何角落定位（watermarkPosition）
• 📏 智能调整大小（图像宽度的25%，保持宽高比）
• 🎯 保持一致的间距（边缘3%的内边距）
• 🖼️ 支持PNG、JPG、WebP格式的水印文件
• ⚡ 仅在提供 watermarkPath 参数时应用

用法：

# 用于图像生成
watermarkPath: "./my-brand-logo.png"

# 使用上下文图像
watermarkPath: "./watermark.jpg"

水印规格：

• 位置：可通过 watermarkPosition 配置角落
• 大小：图像宽度的25%（保持水印宽高比）
• 内边距：所选边缘的图像宽度的3%
• 混合模式：覆盖（水印显示在图像顶部）

保存功能：

• 默认：图像保存到执行MCP客户端的目录
• 自动命名基于描述、日期和时间生成
• 支持的格式：PNG、JPG、WebP（取决于Gemini返回的内容）
• 自动创建：如果所需文件夹不存在，则自动创建

🔧 技术细节

可用脚本

• npm run build：将TypeScript编译为JavaScript
• npm run dev：开发模式，支持自动重新加载
• npm start：运行编译后的服务器

项目结构

gemini-image-mcp-server/
├── src/
│   ├── index.ts          # 主服务器入口点
│   ├── services/
│   │   └── gemini.ts     # Gemini AI服务
│   ├── tools/
│   │   ├── index.ts      # 工具导出
│   │   ├── generateImage.ts  # 创建新图像的工具
│   │   └── editImage.ts      # 编辑现有图像的工具
│   └── types/
│       └── index.ts      # 类型定义
├── dist/                 # 编译后的文件
├── package.json
├── tsconfig.json
└── README.md

🔧 故障排除

错误：“GOOGLE_API_KEY environment variable is required”

确保你已使用谷歌AI的API密钥配置了 GOOGLE_API_KEY 环境变量。

错误：“Could not generate image”

• 验证你的API密钥是否有效，并且对 gemini-2.5-flash-image-preview 模型具有权限
• 确保描述不包含可能被安全过滤器阻止的内容

文件保存错误

• 验证你在指定路径具有写入权限
• 确保路径有效且可访问
• 如果指定文件夹，请以 / 结尾

服务器无响应

• 验证服务器是否正常运行
• 检查标准错误输出中的日志以查找错误消息
• 确保MCP客户端配置正确

📄 许可证

MIT

贡献说明

欢迎贡献代码。在进行重大更改之前，请先创建一个问题。