Gemini MCP

🚀 Gemini MCP Server

這是一個MCP（模型上下文協議）服務器，可用於訪問谷歌的Gemini API。它能直接替代Codex MCP，且接口匹配。

🚀 快速開始

此Gemini MCP Server可幫助你輕鬆訪問谷歌的Gemini API，為各類應用提供智能交互能力。以下是使用前的準備步驟。

✨ 主要特性

• gemini - 開啟一個新的Gemini對話，並可配置上下文。
• gemini-reply - 繼續多輪對話。
• gemini-image - 使用Nano Banana（Gemini原生圖像生成功能）生成圖像。
• gemini-video-generate - 使用Veo 3.1開始視頻生成。
• gemini-video-check - 檢查視頻生成狀態並獲取已完成的視頻。

📦 安裝指南

npm install
npm run build

📚 詳細文檔

配置

創建一個 .env 文件或設置環境變量：

# 必需：你的谷歌Gemini API密鑰
GEMINI_API_KEY=your_api_key_here

# 可選：覆蓋默認模型（默認：gemini-3-pro-preview）
GEMINI_MODEL=gemini-3-pro-preview

你可以從 Google AI Studio 獲取API密鑰。

與Claude Code配合使用

將以下內容添加到你的MCP設置 (~/.claude/mcp.json) 中：

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["/path/to/gemini-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here"
      }
    }
  }
}

工具使用說明

gemini

開啟一個與Gemini的新對話。 參數：

• prompt（必需） - 初始提示信息
• cwd - 工作目錄上下文
• sandbox - 訪問策略："read-only"（只讀）、"workspace-write"（工作區寫入）或 "danger-full-access"（完全危險訪問）
• base-instructions - 覆蓋默認系統指令
• developer-instructions - 為模型提供額外上下文

返回值：響應文本和一個用於後續跟進的 conversationId。

gemini-reply

繼續一個已有的對話。 參數：

• conversationId（必需） - 之前 gemini 調用返回的ID
• prompt（必需） - 你的跟進消息

gemini-image

使用Nano Banana（谷歌內置於Gemini的原生圖像生成功能）生成圖像。 模型：

• Nano Banana (gemini-2.5-flash-image) - 快速、經濟高效（約 $0.04/張圖像），適用於大多數用例
• Nano Banana Pro (gemini-3-pro-image-preview) - 高級模型，文本渲染效果更好，適用於信息圖表、圖表和文本較多的圖像

自動檢測：當你的提示包含以下關鍵詞時，服務器會自動使用Nano Banana Pro：

• "nano banana pro"、"pro model"
• "infographic"（信息圖表）、"diagram"（圖表）、"chart"（圖表）、"graph"（圖形）
• "text"（文本）、"typography"（排版）、"font"（字體）、"lettering"（字母）
• "logo"（標誌）、"brand"（品牌）、"poster"（海報）、"flyer"（傳單）、"banner"（橫幅）
• "slide"（幻燈片）、"presentation"（演示文稿）、"document"（文檔）
• "high quality"（高質量）、"4k"、"detailed text"（詳細文本）

參數：

• prompt（必需） - 要生成圖像的描述
• numberOfImages - 生成圖像的數量（1 - 4，默認：1）
• aspectRatio - 圖像比例："1:1"、"3:4"、"4:3"、"9:16"、"16:9"
• usePro - 強制使用Nano Banana Pro（如果未指定，則根據提示自動檢測）
• outputPath - 保存生成圖像的目錄

示例：

// 自動檢測使用Pro模型
"Create an infographic showing the software development lifecycle"

// 顯式請求使用Pro模型
{ "prompt": "A sunset over mountains", "usePro": true }

// 快速生成（默認）
"A cute cat wearing a hat"

gemini-video-generate

使用Veo 3.1（谷歌的高級視頻生成模型）開始視頻生成。 重要提示：視頻生成是異步的。此工具會立即返回一個操作ID。使用 gemini-video-check 輪詢完成狀態（通常需要30 - 60秒）。 參數：

• prompt（必需） - 要生成視頻的描述
• aspectRatio - 視頻比例："16:9"（默認）、"9:16"
• resolution - 視頻分辨率："480p"、"720p"（默認）
• firstFrameBase64 - 可選的Base64編碼圖像，用作第一幀（可先使用 gemini-image 生成）

返回值：用於檢查狀態的操作ID

示例工作流程：

1. gemini-video-generate: "A cat playing with a ball of yarn"
   → 返回: { operationId: "op-123..." }

2. 等待30 - 60秒

3. gemini-video-check: { operationId: "op-123..." }
   → 返回: { status: "processing", elapsed: "45s" }
   或者
   → 返回: { status: "complete", videoData: "..." }

gemini-video-check

檢查視頻生成操作的狀態並獲取已完成的視頻。 參數：

• operationId - 來自 gemini-video-generate 的操作ID（可選 - 如果省略，則使用最後一個操作）
• outputPath - 保存已完成視頻的目錄

返回值：

• 如果正在處理：狀態和已用時間
• 如果已完成：視頻數據（Base64編碼）和可選的保存文件路徑

💡 使用建議：你可以使用 gemini-image 創建自定義第一幀，然後通過 firstFrameBase64 將其傳遞給 gemini-video-generate，以更好地控制你的視頻。

開發

# 以開發模式運行
npm run dev

# 為生產環境構建
npm run build

# 啟動生產服務器
npm start

📄 許可證

本項目採用MIT許可證。