Gemini MCP Server

🚀 Gemini MCP Server for Claude Desktop

Gemini MCP Server for Claude Desktop 是一個模型上下文協議（MCP）服務器，它能讓 Claude Desktop 使用 Google 的 Gemini AI 模型來生成圖像，為用戶提供了便捷的圖像生成體驗。

🚀 快速開始

本服務器允許 Claude Desktop 使用 Google 的 Gemini AI 模型生成圖像。安裝並配置完成後，重啟 Claude Desktop 即可啟用。

✨ 主要特性

• 🌟 直接在 Claude Desktop 中使用 Google 的 Gemini 模型生成圖像。
• 🔧 提供簡單的設置嚮導，方便進行配置。
• 🎨 可自定義圖像生成參數。
• 🔌 與 Claude Desktop 的 MCP 服務器系統集成。
• 📜 具備詳細的日誌記錄和調試功能。
• 🐳 支持 Docker，便於部署和共享。

📦 安裝指南

全局安裝（推薦）

npm install -g gemini-mcp-server

# 運行設置嚮導
npx gemini-mcp-setup

本地安裝

# 為服務器創建一個目錄
mkdir gemini-mcp-server
cd gemini-mcp-server

# 本地安裝
npm install gemini-mcp-server

# 運行設置嚮導
npx gemini-mcp-setup

Docker 安裝

你也可以使用 Docker 運行 Gemini MCP 服務器：

# 構建 Docker 鏡像
docker build -t gemini-mcp-server .

# 運行 Docker 容器
docker run -e GEMINI_API_KEY="your-api-key" -e OUTPUT_DIR="/app/output" -v /path/on/host:/app/output gemini-mcp-server

⚙️ 配置說明

設置嚮導將引導你完成配置過程：

1. 輸入你的 Google Gemini API 密鑰。
2. 指定保存生成圖像的目錄。
3. 配置日誌記錄和模型設置。
4. 自動為 Claude Desktop 創建包裝腳本。
5. 更新你的 Claude Desktop 配置。

如果你更喜歡手動設置，請參閱下面的 手動配置 部分。

💻 使用示例

基礎用法

安裝並配置完成後，重啟 Claude Desktop 以啟用 Gemini MCP 服務器。然後：

1. 與 Claude 開始對話。
2. 要求 Claude 為你生成圖像，例如：
   • "生成一張日落時分的山脈風景圖"
   • "創建一張帶有飛行汽車的未來城市圖片"
   • "製作一幅貓彈鋼琴的插畫"

Claude 將調用 Gemini API 生成圖像，併為你提供保存的圖像文件路徑。

高級用法

你可以使用額外的參數自定義圖像生成：

• 風格：指定風格，如 "寫實風格"、"藝術風格"、"簡約風格" 等。
• 溫度：控制生成的創造性/隨機性（0.0 - 1.0）。

示例："以寫實風格、溫度 0.7 生成一張帶有霓虹燈的賽博朋克城市圖像"

🔧 手動配置

如果你不想使用設置嚮導，請按照以下步驟操作：

1. 創建配置文件

創建一個包含你設置的 JSON 配置文件：

{
  "apiKey": "YOUR_GEMINI_API_KEY_HERE",
  "outputDir": "/path/to/your/output/directory",
  "debug": true,
  "modelOptions": {
    "model": "gemini-2.0-flash-exp",
    "temperature": 0.4
  }
}

2. 創建包裝腳本

創建一個 bash 腳本來運行服務器：

#!/bin/bash
# 設置環境變量
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY_HERE"
export OUTPUT_DIR="/path/to/your/output/directory"
export DEBUG="true"

# 執行服務器
exec "$(which node)" "$(npm root -g)/gemini-mcp-server/bin/gemini-mcp-server.js"

使腳本可執行：

chmod +x gemini-mcp-wrapper.sh

3. 更新 Claude Desktop 配置

編輯你的 ~/.config/claude/claude_desktop_config.json 文件，添加 Gemini MCP 服務器：

{
  "mcpServers": {
    "gemini-image": {
      "command": "/bin/bash",
      "args": [
        "-c",
        "/path/to/your/gemini-mcp-wrapper.sh"
      ],
      "env": {
        "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY_HERE",
        "DEBUG": "true"
      }
    }
  }
}

🐳 Docker 部署

此 MCP 服務器包含一個 Dockerfile，便於部署和共享。Docker 鏡像配置為：

• 使用 Node.js 16 Alpine 作為輕量級基礎。
• 安裝所有必要的依賴項。
• 在 /app/output 設置默認輸出目錄。
• 允許通過環境變量進行配置。

構建 Docker 鏡像

docker build -t gemini-mcp-server .

使用 Docker 運行

docker run \
  -e GEMINI_API_KEY="your-api-key" \
  -e OUTPUT_DIR="/app/output" \
  -e DEBUG="false" \
  -v /path/on/host:/app/output \
  gemini-mcp-server

Docker 環境變量

運行 Docker 容器時，你可以使用以下環境變量配置服務器：

• GEMINI_API_KEY：你的 Google Gemini API 密鑰（必需）
• OUTPUT_DIR：保存生成圖像的目錄（默認：/app/output）
• DEBUG：啟用調試日誌記錄（默認：false）

與 Claude Desktop 一起使用

當將 Docker 容器與 Claude Desktop 一起使用時，你需要：

1. 確保容器正在運行。
2. 配置 Claude Desktop 以連接到容器化服務器。
3. 將輸出目錄映射到 Claude 可訪問的位置。

📚 詳細文檔

命令行界面

gemini-mcp-server [options]

選項：

• -k, --api-key <key>：Google Gemini API 密鑰
• -o, --output-dir <dir>：保存生成圖像的目錄
• -d, --debug：啟用調試日誌記錄
• -c, --config <path>：自定義配置文件的路徑
• -r, --reset-config：將配置重置為默認值
• -v, --version：顯示版本信息

環境變量

• GEMINI_API_KEY：你的 Google Gemini API 密鑰
• OUTPUT_DIR：保存生成圖像的目錄
• DEBUG：啟用調試日誌記錄（true 或 false）
• LOG_LEVEL：設置日誌級別（ERROR、WARN、INFO 或 DEBUG）
• GEMINI_LOG_FILE：自定義日誌文件路徑

配置選項

🔍 故障排除

常見問題

服務器無法啟動或 Claude 無法連接到服務器

1. 檢查 ~/Claude/logs/gemini-image-mcp.log 處的日誌文件。
2. 驗證你的 API 密鑰是否正確。
3. 確保所有目錄存在並具有適當的權限。
4. 重啟 Claude Desktop。

圖像未生成

1. 驗證你的 Google Gemini API 密鑰是否具有正確的權限。
2. 檢查輸出目錄是否存在且可寫。
3. 檢查日誌以獲取特定的錯誤消息。
4. 嘗試不同的提示或模型。

錯誤："Method not found"

這通常意味著 Claude 試圖調用 MCP 服務器不支持的方法。檢查日誌以查看請求的方法。

Docker 特定問題

1. 確保容器具有適當的網絡連接。
2. 檢查卷掛載是否正確配置。
3. 驗證環境變量是否正確設置。
4. 使用 docker logs [container-id] 查看容器日誌。

調試模式

啟用調試模式以獲取更詳細的日誌：

npx gemini-mcp-server --debug

或者設置環境變量：

export DEBUG=true
npx gemini-mcp-server

📄 許可證

本項目採用 MIT 許可證。

🙏 致謝

• Model Context Protocol 提供 MCP 規範。
• Google Generative AI 提供 Gemini API。
• 本項目的所有貢獻者。