Gemini MCP Ultimate

Gemini MCP终极版

Gemini CLI的最终模型上下文协议（MCP）服务器

*用谷歌的Gemini 3 Pro、巨大的1M+令牌上下文窗口和持久会话为克劳德充电。*

安装 • 用法 • 工具 • 故障排除

______________________________________________________________________

为什么使用这个？

问题：Claude的上下文窗口需要令牌。反复阅读50000行代码库会消耗掉API的预算。

解决方案：将大文件分析卸载到Gemini的1M+令牌上下文窗口。克劳德问问题，双子座搜索记忆，你只为答案付费。

______________________________________________________________________

目录

• 安装

- 先决条件 - 快速安装 - 平台特定说明 - 验证安装

• 代币节省示例
• 工具参考
• 使用示例
• 故障排除
• Windows兼容性
• 许可证

______________________________________________________________________

安装

先决条件

快速安装

对于Claude Code（CLI）：

claude mcp add gemini-mcp-ultimate -- npx -y gemini-mcp-ultimate

对于Claude Desktop：

添加到MCP配置文件中：

{
  "mcpServers": {
    "gemini-mcp-ultimate": {
      "command": "npx",
      "args": ["-y", "gemini-mcp-ultimate"]
    }
  }
}

平台特定说明

Linux/macOS

1. 安装Node.js （如果尚未安装）：

   # Using nvm (recommended)
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   nvm install 20
   nvm use 20

1. 全局安装Gemini CLI：

   npm install -g @google/gemini-cli

1. 与Gemini进行身份验证：

   gemini
   # Follow the browser prompts to sign in with your Google account

1. 添加MCP服务器：

   claude mcp add gemini-mcp-ultimate -- npx -y gemini-mcp-ultimate

1. 重新启动Claude代码 加载新的MCP服务器。

视窗

重要：使用 PowerShell 对于所有Windows命令，不是命令提示符（cmd.exe）。PowerShell正确地保留了MCP服务器定位Gemini所需的系统PATH和环境变量。

Windows需要额外的PATH配置，因为MCP服务器在可能不继承用户PATH的隔离环境中运行。

1. 打开PowerShell （非命令提示符）：

- 按 Win + X 然后选择“Windows PowerShell”或“终端” - 或者在“开始”菜单中搜索“PowerShell” - 不要使用 cmd.exe 因为它可能没有正确的路径

1. 安装Node.js：

- 下载自 （推荐LTS） - 或使用 nvm窗口:

     # After installing nvm-windows
     nvm install 20
     nvm use 20

1. 全局安装Gemini CLI （在PowerShell中）：

   npm install -g @google/gemini-cli

1. 通过Gemini进行身份验证 （在PowerShell中）：

   gemini
   # Follow the browser prompts to sign in with your Google account

1. 验证Gemini是否可用 （在PowerShell中）：

   # Check that gemini.cmd exists in your npm global path
   Get-Command gemini
   # Should output the path, e.g.: C:\Users\YourName\AppData\Roaming\npm\gemini.cmd

   # Alternative using where.exe
   where.exe gemini

1. 验证是否设置了环境变量 （对nvm windows用户很重要）：

   # Check these are set correctly
   $env:PATH -split ';' | Where-Object { $_ -match 'node|npm|nvm' }

   # For nvm-windows users, verify these exist:
   echo $env:NVM_HOME
   echo $env:NVM_SYMLINK

1. 添加MCP服务器 （在PowerShell中）：

   claude mcp add gemini-mcp-ultimate -- npx -y gemini-mcp-ultimate

1. 重新启动Claude代码 加载新的MCP服务器。

1. 如果MCP服务器找不到Gemini，请参阅 Windows故障排除 在......下面

验证安装

安装后，验证MCP服务器是否正常工作：

1. 打开克劳德代码或克劳德桌面
2. 类型 /mcp 查看已连接的服务器
3. 你应该看到 gemini-mcp-ultimate 上市
4. 测试：“用双子座告诉我2+2等于什么”

______________________________________________________________________

代币节省示例

示例1：代码库分析

场景：分析一个包含50个文件的15000行代码的React应用程序。

没有Gemini MCP（传统方法）：

User: "Explain the authentication flow in this codebase"
Claude: [Reads 50 files = ~60,000 tokens input]
Claude: [Generates response = ~2,000 tokens output]
Total: ~62,000 tokens per question

使用Gemini MCP：

# First query - Gemini ingests the codebase once
User: "Ask Gemini to analyze @src/ and explain the authentication flow"
Claude: [Calls ask-gemini tool = ~200 tokens]
Gemini: [Reads files into its 1M context, returns summary = ~1,500 tokens returned]
Total first query: ~1,700 tokens

# Subsequent queries - No file re-reading
User: "What middleware is used for auth?"
Claude: [Calls ask-gemini with session_id = ~150 tokens]
Gemini: [Queries existing context, returns answer = ~500 tokens]
Total: ~650 tokens per follow-up

代币节省：

示例2：文档审查

场景：查看200页的API文档PDF转换为降价（约100000个代币）。

# Load documentation into Gemini session
User: "Use Gemini to read @docs/api-reference.md and create a session for questions"

# Query specific endpoints without re-reading
User: "What are the rate limits for the /users endpoint?"
User: "Show me authentication header examples"
User: "What error codes can the /orders endpoint return?"

每次后续查询花费约500-1000个令牌，而不是约100000个令牌。

示例3：多文件重构

场景：重构20个实用程序文件的错误处理。

# Gemini analyzes all files once
User: "Ask Gemini to review @src/utils/*.ts for inconsistent error handling"
Gemini: Returns analysis and patterns found

# Claude applies fixes based on Gemini's analysis
User: "Apply the suggested error handling pattern to all files"
Claude: Uses Gemini's recommendations without re-reading all files

______________________________________________________________________

工具参考

ask-gemini

与Gemini CLI交互的主要工具。

示例提示：

# Analyze a single file
"@src/index.ts explain the main entry point"

# Analyze multiple files
"@src/auth/*.ts @src/middleware/*.ts how does authentication work?"

# Resume a session
prompt: "What about the error handling?"
session_id: "5"

# Autonomous mode
prompt: "@src/utils/ fix all TypeScript errors"
approval_mode: "auto_edit"

brainstorm

使用结构化框架进行创造性思维。

例子：

prompt: "Ways to reduce API response times"
domain: "software"
methodology: "scamper"
ideaCount: 5

manage-sessions

列出或删除Gemini对话会话。

例子：

# List all sessions
action: "list"

# Delete a specific session
action: "delete"
session_id: "3"

manage-extensions

安装和管理Gemini CLI扩展。

例子：

# List installed extensions
action: "list"

# Install an extension
action: "install"
target: "conductor"

# Update all extensions
action: "update"
all: true

ping

测试与MCP服务器的连接。

prompt: "Hello from test"
# Returns: cmd "Hello from test"

Help

显示Gemini CLI帮助信息。

# No parameters needed
# Returns full Gemini CLI help text

______________________________________________________________________

使用示例

1.基础档案分析

用户提示：

“使用Gemini解释@src/utils/commandExecutor.ts的作用”

发生了什么：

1. 克劳德打电话来 ask-gemini 带有文件引用
2. Gemini读取文件并对其进行分析
3. 向Claude返回解释
4. 克劳德给出了答案

2.多圈代码库会话

第一个查询：

“让Gemini分析@src/并创建一个我可以查询的会话”

克劳德来电：

{
  "tool": "ask-gemini",
  "prompt": "@src/ analyze this codebase structure and key components"
}

跟进（使用会话）：

“在同一个会话中，错误处理是如何工作的？”

克劳德来电：

{
  "tool": "ask-gemini",
  "prompt": "Explain the error handling patterns in this codebase",
  "session_id": "latest"
}

好处： 第二个查询不会重新读取任何文件。Gemini质疑其现有的背景。

3.自主代码修复

“在自动编辑模式下使用Gemini修复@src/中的所有ESLint错误”

克劳德来电：

{
  "tool": "ask-gemini",
  "prompt": "@src/ fix all ESLint errors",
  "approval_mode": "auto_edit"
}

Gemini直接修复文件，无需每次编辑都要求确认。

4.头脑风暴会议

“头脑风暴5种使用设计思维改善CLI开发人员体验的方法”

克劳德来电：

{
  "tool": "brainstorm",
  "prompt": "Ways to improve CLI developer experience",
  "methodology": "design-thinking",
  "ideaCount": 5,
  "domain": "software"
}

5.扩展管理

“安装Gemini安全扩展”

克劳德来电：

{
  "tool": "manage-extensions",
  "action": "install",
  "target": "https://github.com/gemini-cli-extensions/security"
}

6.会话清理

“列出我的双子座会话并删除旧会话”

克劳德来电：

{
  "tool": "manage-sessions",
  "action": "list"
}

然后进行删除：

{
  "tool": "manage-sessions",
  "action": "delete",
  "session_id": "2"
}

______________________________________________________________________

故障排除

一般问题

MCP服务器未出现在 /mcp 列表：

1. 完全重新启动克劳德代码/桌面
2. 检查是否安装了Node.js： node --version
3. 验证npx是否正常工作： npx --version

“找不到Gemini命令”错误：

1. 安装Gemini CLI： npm install -g @google/gemini-cli
2. 验证安装： gemini --version
3. 重新验证： gemini （按照提示操作）

超出配额错误：

• 服务器自动从以下位置回退 gemini-3-pro-preview 到 gemini-3-flash-preview
• 您可以明确地请求flash： model: "gemini-3-flash-preview"

Windows故障排除

始终使用PowerShell 用于故障排除。命令提示符（cmd.exe）未正确继承环境变量。

Windows面临着独特的挑战，因为：

1. npm全局命令是 .cmd 批处理文件，而非可执行文件
2. MCP服务器在没有用户PATH的隔离环境中运行
3. Node.js可以通过非标准路径的nvm窗口安装

如果找不到双子座：

1. 打开PowerShell并找到您的Gemini安装：

   # Use Get-Command (PowerShell native)
   Get-Command gemini | Select-Object Source

   # Or use where.exe (note the .exe to avoid PowerShell alias)
   where.exe gemini
   # Example output: C:\Users\YourName\AppData\Roaming\npm\gemini.cmd

1. 验证你的PATH是否包含npm全局目录：

   # List PATH entries containing npm or node
   $env:PATH -split ';' | Where-Object { $_ -match 'npm|node|nvm' }

   # Check if npm global bin is in PATH
   $npmGlobal = Join-Path $env:APPDATA 'npm'
   if ($env:PATH -match [regex]::Escape($npmGlobal)) {
       Write-Host "npm global path is in PATH" -ForegroundColor Green
   } else {
       Write-Host "npm global path is NOT in PATH" -ForegroundColor Red
       Write-Host "Add this to your PATH: $npmGlobal"
   }

1. 验证NVM环境变量 （如果使用nvm窗口）：

   # These should both return paths if nvm-windows is configured correctly
   echo "NVM_HOME: $env:NVM_HOME"
   echo "NVM_SYMLINK: $env:NVM_SYMLINK"

   # Verify the symlink points to a valid Node installation
   if ($env:NVM_SYMLINK) {
       Test-Path (Join-Path $env:NVM_SYMLINK 'node.exe')
   }

1. MCP服务器自动检测这些路径 （按优先顺序）：

- $env:NVM_SYMLINK （nvm windows活动版本符号链接） - $env:APPDATA\npm （标准npm全局） - $env:NVM_HOME\vX.X.X （nvm windows安装版本） - C:\Program Files\nodejs （标准Node.js安装）

1. 如果自动检测失败，在PowerShell中从源代码安装：

   git clone https://github.com/GlitterKill/gemini-mcp-ultimate.git
   cd gemini-mcp-ultimate
   npm install
   npm run build

   # Add with full path (adjust path as needed)
   $fullPath = (Resolve-Path .\dist\index.js).Path
   claude mcp add gemini-local -- node $fullPath

1. 验证MCP服务器能否找到Gemini 通过检查日志：

   # Run the MCP server directly to see debug output
   $env:DEBUG = "true"
   node .\dist\index.js
   # Look for "Resolved gemini to..." in the output

______________________________________________________________________

Windows兼容性

此项目包括上游中不存在的Windows关键修复程序 gemini-mcp-tool.

问题

在Unix系统上，npm全局命令如 gemini 是可执行脚本。在Windows上，他们 .cmd 批处理文件(gemini.cmd).Node.js child_process.spawn() 无法执行 .cmd 文件直接没有 shell: true，但使用 shell: true 触发Node.js弃用警告和安全问题。

解决方案

这 commandExecutor.ts 模块(src/utils/commandExecutor.ts:82-116)实现平台感知命令执行：

在Windows上：

// Uses cmd.exe /c to execute .cmd files
spawnCommand = 'C:\\Windows\\System32\\cmd.exe';
spawnArgs = ['/c', 'gemini.cmd', ...args];

在Linux/macOS上：

// Direct execution
spawnCommand = 'gemini';
spawnArgs = args;

其他Windows修复程序

1. PATH环境注入：由于MCP服务器不继承用户PATH，因此服务器将公共Node.js/npm路径添加到子进程环境中。

1. NVM Windows支持：自动检测 NVM_HOME 和 NVM_SYMLINK 使用nvm窗口的用户的环境变量。

1. 完整路径分辨率：搜索多个位置以查找 gemini.cmd:

- %NVM_SYMLINK%\gemini.cmd - %APPDATA%\npm\gemini.cmd - %NVM_HOME%\vX.X.X\gemini.cmd - C:\Program Files\nodejs\gemini.cmd

______________________________________________________________________

发展

从源头构建

git clone https://github.com/GlitterKill/gemini-mcp-ultimate.git
cd gemini-mcp-ultimate
npm install
npm run build

本地运行

# Build and run
npm run dev

# Or just run after building
node dist/index.js

添加到Claude Code（本地开发）

claude mcp add gemini-dev -- node /path/to/gemini-mcp-ultimate/dist/index.js

项目结构

src/
├── index.ts                 # MCP server entry point
├── constants.ts             # Shared constants
├── tools/
│   ├── registry.ts          # Tool registration system
│   ├── ask-gemini.tool.ts   # Main Gemini interface
│   ├── brainstorm.tool.ts   # Brainstorming tool
│   └── ...
└── utils/
    ├── commandExecutor.ts   # Platform-aware process spawning
    ├── geminiExecutor.ts    # Gemini CLI command builder
    └── ...

______________________________________________________________________

贡献

欢迎捐款。拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 跑 npm run lint 检查错误
5. 提交拉取请求

______________________________________________________________________

许可证

MIT许可证-请参阅 许可证 了解详情。

______________________________________________________________________

学分

• 原始项目： jamubc/gemini mcp工具
• Windows兼容性修复和增强 GlitterKill