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 优化分支。对于其他平台，建议使用 原始版本。