Gemini 2.5 Flash Image MCP

🚀 Gemini 2.5 Flash Image MCP

Gemini 2.5 Flash Image MCP 是一個模型上下文協議（MCP）服務器，可藉助 Google 的 Gemini 2.5 Flash Image 預覽版進行對話式圖像生成與編輯。它易於安裝，可通過 Claude Code 及其他 MCP 客戶端使用。

✨ 主要特性

• 文本到圖像：根據詳細提示詞生成圖像
• 圖像編輯：使用自然語言指令編輯圖像
• 多圖像合成/風格遷移：組合圖像或遷移風格
• 文件保存選項：返回 base64 格式圖像，並可選擇保存到文件
• 與供應商無關的 MCP：可在任何支持 MCP 的客戶端中使用

📦 安裝指南

系統要求

• Node.js 18 或更高版本
• 一個 MCP 客戶端（Claude Code、Cursor、VS Code、Windsurf 等）
• Google Gemini API 密鑰：設置 GEMINI_API_KEY

獲取 Gemini API 密鑰

按照以下步驟從 Google AI Studio 獲取 API 密鑰：

1. 打開 Google AI Studio 並登錄：https://aistudio.google.com/apikey
2. 點擊“創建 API 密鑰”（若已有密鑰則點擊“管理密鑰”）
3. 複製生成的密鑰
4. 在運行此服務器時，將其設置為機器上的環境變量

示例：

# macOS / Linux (bash/zsh)
export GEMINI_API_KEY="YOUR_API_KEY"

# Windows PowerShell
$env:GEMINI_API_KEY="YOUR_API_KEY"

🚀 快速開始

首先，將 MCP 服務器與你的客戶端進行安裝。以下示例以 Claude Code 的使用為主。

標準配置

標準配置適用於大多數工具：

{
  "mcpServers": {
    "gemini-2-5-flash-mcp": {
      "command": "npx",
      "args": ["@taiyokimura/gemini-2-5-flash-mcp@latest"]
    }
  }
}

快速使用（Claude Code）

# npx（帶非交互標誌）+ 同時指定 API 密鑰（Claude 的 -e 指定）
claude mcp add gemini-2-5-flash-mcp -s user -e GEMINI_API_KEY="YOUR_API_KEY" -- npx -y @taiyokimura/gemini-2-5-flash-mcp@latest

# 全局安裝 + 同時指定 API 密鑰（Claude 的 -e 指定）
npm i -g @taiyokimura/gemini-2-5-flash-mcp \
  && claude mcp add gemini-2-5-flash-mcp -s user -e GEMINI_API_KEY="YOUR_API_KEY" -- gemini-2-5-flash-mcp

# HTTP 模式註冊示例（SSE 為默認）（僅適用於支持的客戶端）
# ※ HTTP 模式下，此進程將作為 HTTP 服務器常駐
claude mcp add gemini-2-5-flash-mcp -s user \
  -e GEMINI_API_KEY="YOUR_API_KEY" \
  -e MCP_TRANSPORT="http" \
  -e MCP_HTTP_PORT="7801" \
  -e MCP_HTTP_PATH="/mcp" \
  -- npx -y @taiyokimura/gemini-2-5-flash-mcp@latest

可流式傳輸的 HTTP 模式（實驗性）

也可以使用可流式傳輸的 HTTP 代替 STDIO。僅在 MCP 客戶端支持可流式傳輸的 HTTP 時使用。

1. 以 HTTP 模式啟動服務器

export MCP_TRANSPORT=http
export GEMINI_API_KEY=YOUR_API_KEY
# 可選（默認值: 7801, /mcp, SSE）
export MCP_HTTP_PORT=7801
export MCP_HTTP_PATH=/mcp
export MCP_HTTP_ENABLE_JSON=false

npm run build
node ./build/index.js
# => HTTP 傳輸監聽地址：http://localhost:7801/mcp

2. 客戶端配置（示例：支持可流式傳輸的 HTTP 的客戶端）

• 類型：HTTP (可流式傳輸)
• URL：http://localhost:7801/mcp

注：

• SSE 流式傳輸為默認設置。若要使用 JSON 響應，請設置 MCP_HTTP_ENABLE_JSON=true。
• 會話在服務器端生成（有狀態）。若要實現完全無狀態，可在代碼中將 sessionIdGenerator: undefined 進行修改。

claude mcp add gemini-2-5-flash-mcp -s user -- npx @taiyokimura/gemini-2-5-flash-mcp@latest

claude mcp remove gemini-2-5-flash-mcp

code --add-mcp '{"name":"gemini-2-5-flash-mcp","command":"npx","args":["@taiyokimura/gemini-2-5-flash-mcp@latest"]}'

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gemini-2-5-flash-mcp": {
      "type": "本地",
      "命令": [
        "npx",
        "@taiyokimura/gemini-2-5-flash-mcp@latest"
      ],
      "啟用": true
    }
  }
}

📚 詳細文檔

環境變量

• GEMINI_API_KEY（必需）
• GEMINI_IMAGE_ENDPOINT（可選）默認值： https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image-preview:generateContent
• MCP_NAME（可選，默認值：gemini-2-5-flash-mcp）

可用工具

1. generate_image

根據文本提示詞生成圖像。

參數：

• prompt（必需）：用於生成圖像的詳細描述
• saveToFilePath（可選）：保存圖像的路徑

示例輸入：

{
  "prompt": "創建一張帶有 Gemini 主題的高檔餐廳裡的納米香蕉菜餚的圖片",
  "saveToFilePath": "./gemini-native-image.png"
}

2. edit_image

使用提示詞編輯圖像。

參數：

• prompt（必需）：編輯指令
• image（必需）：{ dataBase64?: string, path?: string, mimeType?: string }
• saveToFilePath（可選）

示例輸入：

{
  "prompt": "給貓添加一頂小的針織巫師帽",
  "image": { "path": "./cat.jpeg", "mimeType": "image/jpeg" },
  "saveToFilePath": "./gemini-edited-image.png"
}

3. compose_images

組合多個圖像的元素。

參數：

• prompt（必需）
• images（必需）：圖像輸入數組（建議 2 - 3 個）
• saveToFilePath（可選）

4. style_transfer

將一個圖像的風格遷移到另一個圖像。

參數：

• prompt（可選）
• baseImage（必需）
• styleImage（必需）
• saveToFilePath（可選）

🔧 技術細節

本地運行

npm install
npm run build
npx .

名稱一致性與故障排除

• 始終使用規範標識符（CANONICAL_ID）gemini-2-5-flash-mcp 作為標識符和鍵。
• 僅在 UI 標籤中使用規範顯示名稱（CANONICAL_DISPLAY）Gemini 2.5 Flash MCP。
• 不要在不同客戶端中混用不同名稱。

一致性矩陣：

衝突清理：

• 刪除任何舊的條目（如 "GeminiFlash"），並使用 gemini-2-5-flash-mcp 重新添加。
• 確保全局註冊表僅使用 gemini-2-5-flash-mcp 作為鍵。
• Cursor：僅在 UI 中進行配置。此項目不包含 .cursor/mcp.json。

📄 參考資料

• MCP SDK：https://modelcontextprotocol.io/docs/sdks
• 架構：https://modelcontextprotocol.io/docs/learn/architecture
• 服務器概念：https://modelcontextprotocol.io/docs/learn/server-concepts
• 服務器規範（2025-06-18）：https://modelcontextprotocol.io/specification/2025-06-18/server/index
• Gemini 圖像生成：https://ai.google.dev/gemini-api/docs/image-generation