Gemini MCP Tool Windows Fixed

🚀 Gemini MCP Tool - Windows 修復版

Gemini MCP Tool - Windows 修復版是一款兼容 Windows 的模型上下文協議（MCP）服務器，它能讓 AI 助手與 Google 的 Gemini CLI 進行交互。此版本專為 Windows 環境量身定製，支持 PowerShell，解決了原版在 Windows 系統中存在的諸多問題。

🚀 快速開始

前提條件

在使用此工具之前，請確保您具備以下條件：

1. Node.js（v16.0.0 或更高版本）

   node --version  # 版本應不低於 v16
   

2. Google Gemini CLI 已安裝並配置好

   npm install -g @google/generative-ai-cli
   
   # 驗證安裝
   gemini --version
   

3. API 密鑰：從 Google AI Studio 獲取您的 API 密鑰。

安裝步驟

使用 NPX 快速開始（推薦）

# 使用最新版本（推薦）
npx gemini-mcp-tool-windows-fixed@1.0.21

# 或使用最新版本標籤
npx -y gemini-mcp-tool-windows-fixed@latest

全局安裝

# 安裝最新版本
npm install -g gemini-mcp-tool-windows-fixed@1.0.21

# 運行工具
gemini-mcp-tool-windows-fixed

更新現有安裝

如果您之前安裝了舊版本：

# 卸載舊版本並安裝最新版本
npm uninstall -g gemini-mcp-tool-windows-fixed
npm cache clean --force
npm install -g gemini-mcp-tool-windows-fixed@1.0.21

MCP 客戶端配置

Claude Code（一鍵設置）

# 為 Claude Code 進行一鍵設置
claude mcp add gemini-cli -- npx -y gemini-mcp-tool-windows-fixed@1.0.21

驗證安裝：在 Claude Code 中輸入 /mcp 以驗證 gemini-cli MCP 是否激活。 1

替代方法：從 Claude Desktop 導入

如果您已在 Claude Desktop 中進行了配置：

1. 添加到您的 Claude Desktop 配置中（見下文）。
2. 導入到 Claude Code：

   claude mcp add-from-claude-desktop
   

Trae AI（推薦）

1. 打開：%APPDATA%\Trae\User\mcp.json。
2. 添加以下配置：

{
  "mcpServers": {
    "gemini-cli": {
      "name": "gemini-cli",
      "description": "Windows 兼容的 Gemini MCP 工具",
      "baseUrl": "",
      "command": "npx",
      "args": [
        "-y",
        "gemini-mcp-tool-windows-fixed@1.0.21"
      ],
      "env": {
        "GEMINI_API_KEY": "YOUR_ACTUAL_API_KEY_HERE"
      },
      "isActive": true,
      "providerUrl": "https://github.com/orzcls/gemini-mcp-tool-windows-fixed"
    }
  }
}

Claude Desktop

1. 打開：%APPDATA%\Claude\claude_desktop_config.json。
2. 添加以下配置：

{
  "mcpServers": {
    "gemini-cli": {
      "command": "npx",
      "args": ["-y", "gemini-mcp-tool-windows-fixed@1.0.21"],
      "env": {
        "GEMINI_API_KEY": "YOUR_ACTUAL_API_KEY_HERE"
      }
    }
  }
}

API 密鑰配置

選項 1：MCP 配置（推薦）

將上述配置中的 YOUR_ACTUAL_API_KEY_HERE 替換為您的實際 API 密鑰。

選項 2：環境變量

# 臨時設置（當前會話）
$env:GEMINI_API_KEY = "your-actual-api-key"

# 永久設置（用戶級別）
[Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "your-actual-api-key", "User")

# 驗證
echo $env:GEMINI_API_KEY

配置文件位置

Claude Desktop：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/claude/claude_desktop_config.json

Trae AI：

• Windows：%APPDATA%\Trae\User\mcp.json

✨ 主要特性

• 🪟 兼容 Windows：全面支持 PowerShell，並針對 Windows 進行了路徑處理。
• 📊 大上下文窗口：利用 Gemini 的大量令牌窗口來分析整個代碼庫。
• 📁 文件分析：使用 @filename 語法分析文件。
• 🔒 沙盒模式：提供安全的代碼執行環境。
• 🔗 MCP 集成：與支持 MCP 的 AI 助手（如 Trae AI、Claude Desktop）無縫集成。
• ⚡ 支持 NPX：使用 NPX 輕鬆安裝和使用。
• 🔧 支持環境變量：靈活配置 API 密鑰。

此 Windows 修復版解決了以下問題：

• PowerShell 參數傳遞問題。
• 中文/Unicode 文本的字符編碼問題。
• Windows 上的命令行參數轉義問題。
• 環境變量處理問題。

🆕 最新更新

v1.0.21 更新

• 🔧 修復跨終端兼容性問題：解決了不同終端環境中 Node.js 路徑未找到的問題。
• 📦 修復 fetch-chunk 格式錯誤：修復了分塊響應中 MCP 協議格式不匹配的問題。
• 🛡️ 增強 PATH 環境變量處理：自動添加常見的 Node.js 安裝路徑。
• ✅ 完全兼容所有終端：支持 PowerShell、CMD、VS Code 終端、Trae AI、CherryStudio 等。
• 🚀 改進錯誤處理：提供更好的錯誤消息和調試輸出。

v1.0.3 更新

• 🆕 支持 PowerShell 路徑參數：添加了可選的 powershellPath 參數，允許用戶自定義 PowerShell 可執行文件的路徑。
• ✅ 修復 PowerShell 執行錯誤：解決了 spawn powershell.exe ENOENT 問題。
• ✅ 提高 Windows 兼容性：自動檢測可用的 PowerShell 版本。
• ✅ 修復未定義變量錯誤：修復了 executeCommandWithPipedInput 函數中的 args 變量問題。
• ✅ 增強錯誤處理：提供更好的錯誤消息和調試輸出。
• ✅ 向後兼容：現有配置無需修改，自動使用默認檢測邏輯。

💻 使用示例

自然語言示例 2

帶有文件引用（使用 @ 語法）

• "請 Gemini 分析 @src/main.js 並解釋其功能"
• "使用 Gemini 總結 @. 當前目錄"
• "分析 @package.json 並告訴我有關依賴項的信息"

一般問題（無文件）

• "請 Gemini 搜索最新的科技新聞"
• "使用 Gemini 解釋 div 居中的方法"
• "請 Gemini 提供與 @file_im_confused_about 相關的 React 開發最佳實踐"
• "使用 Gemini 解釋 index.html"
• "使用 Gemini 理解大型項目"
• "請 Gemini 搜索最新新聞"

使用 Gemini CLI 的沙盒模式 (-s) 2

沙盒模式允許您在隔離環境中安全地測試代碼更改、運行腳本或執行潛在的危險操作。

• "使用 Gemini 沙盒創建並運行一個處理數據的 Python 腳本"
• "請 Gemini 安全地測試 @script.py 並解釋其功能"
• "使用 Gemini 沙盒安裝 numpy 並創建數據可視化"
• "安全地測試此代碼：創建一個向 API 發出 HTTP 請求的腳本"

斜槓命令（適用於 Claude Code 用戶） 2

您可以在 Claude Code 的界面中直接使用這些命令（與其他客戶端的兼容性尚未測試）：

• /analyze：使用 Gemini 分析文件或目錄，或提出一般問題
  • prompt（必需）：分析提示。使用 @ 語法包含文件（例如，/analyze prompt:@src/ 總結此目錄）或提出一般問題（例如，/analyze prompt:請使用網絡搜索查找最新的新聞報道）
• /sandbox：在 Gemini 的沙盒環境中安全地測試代碼或腳本
  • prompt（必需）：代碼測試請求（例如，/sandbox prompt:創建並運行一個處理 CSV 數據的 Python 腳本 或 /sandbox prompt:@script.py 安全地測試此腳本）
• /help：顯示 Gemini CLI 幫助信息
• /ping：測試與服務器的連接
  • message（可選）：要回顯的消息

可用工具

• ask-gemini：向 Gemini 發送提示

  "解釋 MCP 的工作原理"
  

• analyze-file：使用 @filename 語法分析特定文件

  "分析 @package.json 並提出改進建議"
  

• sandbox-mode：在安全環境中執行代碼

  "在沙盒模式下運行此 Python 代碼：print('Hello World')"
  

🛠️ 可用工具詳情

1. ask-gemini

與 Google Gemini 進行交互以進行分析和提問。 參數：

• prompt（必需）：分析請求。使用 @ 語法引用文件。
• model（可選）：要使用的 Gemini 模型（默認：gemini-2.5-pro）。
• sandbox（可選）：啟用沙盒模式以安全執行代碼。
• changeMode（可選）：啟用結構化更改模式。
• chunkIndex（可選）：用於繼續的塊索引。
• chunkCacheKey（可選）：用於繼續的緩存鍵。

2. brainstorm

使用各種頭腦風暴框架生成創意。 參數：

• prompt（必需）：頭腦風暴挑戰或問題。
• model（可選）：要使用的 Gemini 模型。
• methodology（可選）：框架（divergent、convergent、scamper、design-thinking、lateral、auto）。
• domain（可選）：領域上下文（software、business、creative 等）。
• constraints（可選）：已知的限制或要求。
• existingContext（可選）：背景信息。
• ideaCount（可選）：要生成的創意數量（默認：12）。
• includeAnalysis（可選）：包括可行性分析（默認：true）。

3. fetch-chunk

從 changeMode 響應中檢索緩存的塊。 參數：

• cacheKey（必需）：初始響應中的緩存鍵。
• chunkIndex（必需）：要檢索的塊索引（從 1 開始）。

4. timeout-test

測試超時預防機制。 參數：

• duration（必需）：持續時間（以毫秒為單位，最小值：10ms）。

5. ping

測試與服務器的連接。 參數：

• prompt（可選）：要回顯的消息。

6. Help

顯示可用工具的幫助信息。

🔧 Windows 特定修復

此版本包含以下針對 Windows 的改進：

• PowerShell 參數處理：修復了參數傳遞問題，避免參數拆分。
• 字符編碼：正確處理中文和 Unicode 字符的 UTF-8 編碼。
• 引號轉義：正確轉義命令參數中的引號。
• 環境變量：改進了 .env 文件加載和環境變量處理。
• 路徑解析：支持 Windows 兼容的路徑處理。

🧪 測試安裝

1. 測試 Gemini CLI

gemini -p "Hello, how are you?"

2. 測試 MCP 工具

npx -y gemini-mcp-tool-windows-fixed
# 應顯示：[GMCPT] Gemini CLI MCP Server (Fixed) started

3. 測試 MCP 集成

1. 重啟您的 MCP 客戶端（Trae AI、Claude Desktop）。
2. 嘗試提問："使用 Gemini 解釋 MCP 是什麼"。
3. 檢查是否收到成功響應。

🐛 故障排除

常見問題

"Command not found: gemini"

npm install -g @google/generative-ai-cli

"API key not found"

# 檢查 API 密鑰是否已設置
echo $env:GEMINI_API_KEY

# 如果為空，則進行設置
$env:GEMINI_API_KEY = "your-api-key"

"Permission denied"

# 檢查執行策略
Get-ExecutionPolicy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

如需詳細的故障排除信息，請參閱 INSTALL-GUIDE.md。

🤝 貢獻代碼

歡迎貢獻代碼！請按以下步驟操作：

1. 分叉倉庫。
2. 創建功能分支。
3. 在 Windows 環境中進行測試。
4. 提交拉取請求。

📄 許可證

本項目採用 MIT 許可證，請參閱 LICENSE 文件以獲取詳細信息。

🙏 致謝

• 原始項目：jamubc/gemini-mcp-tool
• Google Gemini CLI 團隊
• 模型上下文協議（MCP）社區

📞 支持

如果您遇到任何問題或有疑問：

1. 查看 Issues 頁面。
2. 創建一個新問題，並詳細描述您遇到的問題。
3. 提供您的 Windows 版本、Node.js 版本和錯誤消息。

為 Windows 開發者精心打造 ❤️

注意：這是原始 gemini-mcp-tool 的 Windows 優化分支。對於其他平臺，建議使用 原始版本。