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

貢獻說明

歡迎貢獻代碼。在進行重大更改之前，請先創建一個問題。