The Ultimate Model Context Protocol (MCP) Server for Gemini CLI

Supercharge Claude with Google's Gemini 3 Pro, massive 1M+ token context windows, and persistent sessions.

Installation • Usage • Tools • Troubleshooting

Problem: Claude's context window costs tokens. Reading a 50,000-line codebase repeatedly burns through your API budget.

Solution: Offload large file analysis to Gemini's 1M+ token context window. Claude asks questions, Gemini searches its memory, you pay only for the answers.

• Installation
  • Prerequisites
  • Quick Install
  • Platform-Specific Instructions
  • Verify Installation
• Token Savings Examples
• Tools Reference
• Usage Examples
• Troubleshooting
• Windows Compatibility
• License

For Claude Code (CLI):

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

For Claude Desktop:

Add to your MCP configuration file:

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

1. Install Node.js (if not already installed):

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

2. Install Gemini CLI globally:

   npm install -g @google/gemini-cli

3. Authenticate with Gemini:

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

4. Add the MCP server:

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

5. Restart Claude Code to load the new MCP server.

Important: Use PowerShell for all Windows commands, not Command Prompt (cmd.exe). PowerShell properly preserves system PATH and environment variables that the MCP server needs to locate Gemini.

Windows requires additional PATH configuration because MCP servers run in an isolated environment that may not inherit your user PATH.

1. Open PowerShell (not Command Prompt):

   • Press Win + X and select "Windows PowerShell" or "Terminal"
   • Or search for "PowerShell" in the Start menu
   • Do not use cmd.exe as it may not have the correct PATH

2. Install Node.js:

   • Download from nodejs.org (LTS recommended)
   • Or use nvm-windows:

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

3. Install Gemini CLI globally (in PowerShell):

   npm install -g @google/gemini-cli

4. Authenticate with Gemini (in PowerShell):

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

5. Verify Gemini is accessible (in 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

6. Verify environment variables are set (important for nvm-windows users):

   # 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

7. Add the MCP server (in PowerShell):

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

8. Restart Claude Code to load the new MCP server.

9. If the MCP server cannot find Gemini, see Windows Troubleshooting below.

After installation, verify the MCP server is working:

1. Open Claude Code or Claude Desktop
2. Type /mcp to see connected servers
3. You should see gemini-mcp-ultimate listed
4. Test with: "Use Gemini to tell me what 2+2 equals"

Scenario: Analyze a React application with 15,000 lines of code across 50 files.

Without Gemini MCP (Traditional approach):

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

With 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

Token Savings:

Scenario: Review a 200-page API documentation PDF converted to markdown (~100,000 tokens).

# 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?"

Each follow-up query costs ~500-1,000 tokens instead of ~100,000 tokens.

Scenario: Refactor error handling across 20 utility files.

# 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

The primary tool for interacting with Gemini CLI.

Example prompts:

# 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"

Creative ideation using structured frameworks.

Example:

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

List or delete Gemini conversation sessions.

Example:

# List all sessions
action: "list"

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

Install and manage Gemini CLI extensions.

Example:

# List installed extensions
action: "list"

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

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

Test connectivity with the MCP server.

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

Display Gemini CLI help information.

# No parameters needed
# Returns full Gemini CLI help text

User prompt:

"Use Gemini to explain what @src/utils/commandExecutor.ts does"

What happens:

1. Claude calls ask-gemini with the file reference
2. Gemini reads the file and analyzes it
3. Returns explanation to Claude
4. Claude presents the answer

First query:

"Ask Gemini to analyze @src/ and create a session I can query"

Claude calls:

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

Follow-up (using session):

"In that same session, how does error handling work?"

Claude calls:

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

Benefit: The second query doesn't re-read any files. Gemini queries its existing context.

"Use Gemini in auto-edit mode to fix all ESLint errors in @src/"

Claude calls:

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

Gemini fixes files directly without asking for confirmation on each edit.

"Brainstorm 5 ways to improve the CLI developer experience using design thinking"

Claude calls:

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

"Install the Gemini security extension"

Claude calls:

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

"List my Gemini sessions and delete the old ones"

Claude calls:

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

Then for deletion:

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

MCP server not appearing in /mcp list:

1. Restart Claude Code/Desktop completely
2. Check that Node.js is installed: node --version
3. Verify npx works: npx --version

"Gemini command not found" errors:

1. Install Gemini CLI: npm install -g @google/gemini-cli
2. Verify installation: gemini --version
3. Re-authenticate: gemini (follow prompts)

Quota exceeded errors:

• The server automatically falls back from gemini-3-pro-preview to gemini-3-flash-preview
• You can explicitly request flash: model: "gemini-3-flash-preview"

Always use PowerShell for troubleshooting. Command Prompt (cmd.exe) does not properly inherit environment variables.

Windows has unique challenges because:

1. npm global commands are .cmd batch files, not executables
2. MCP servers run in isolated environments without user PATH
3. Node.js may be installed via nvm-windows with non-standard paths

If Gemini cannot be found:

1. Open PowerShell and find your Gemini installation:

   # 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

2. Verify your PATH includes npm global directory:

   # 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"
   }

3. Verify NVM environment variables (if using nvm-windows):

   # 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')
   }

4. The MCP server auto-detects these paths (in order of priority):

   • $env:NVM_SYMLINK (nvm-windows active version symlink)
   • $env:APPDATA\npm (standard npm global)
   • $env:NVM_HOME\vX.X.X (nvm-windows installed versions)
   • C:\Program Files\nodejs (standard Node.js installation)

5. If auto-detection fails, install from source in 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

6. Verify the MCP server can find Gemini by checking logs:

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

This project includes critical fixes for Windows that are not present in the upstream gemini-mcp-tool.

On Unix systems, npm global commands like gemini are executable scripts. On Windows, they're .cmd batch files (gemini.cmd). Node.js child_process.spawn() cannot execute .cmd files directly without shell: true, but using shell: true triggers Node.js deprecation warnings and security concerns.

The commandExecutor.ts module (src/utils/commandExecutor.ts:82-116) implements platform-aware command execution:

On Windows:

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

On Linux/macOS:

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

1. PATH Environment Injection: The server adds common Node.js/npm paths to the subprocess environment since MCP servers don't inherit user PATH.

2. NVM-Windows Support: Automatically detects NVM_HOME and NVM_SYMLINK environment variables for users with nvm-windows.

3. Full Path Resolution: Searches multiple locations to find 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 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
    └── ...

Contributions are welcome. Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run npm run lint to check for errors
5. Submit a pull request

MIT License - see LICENSE for details.

• Original project: jamubc/gemini-mcp-tool
• Windows compatibility fixes and enhancements by GlitterKill