Gemini MCP Ultimate

<div align="center">

<img src="assets/mascot.webp" alt="Gemini MCP Ultimate Mascot" width="200">

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

</div>

---

Why Use This?

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.

Scenario	Without Gemini MCP	With Gemini MCP	Savings
Analyze 10,000-line codebase	~40,000 tokens/query	~500 tokens/query	98%
Review 500-page documentation	~200,000 tokens/query	~1,000 tokens/query	99.5%
Multi-file refactoring	Re-read all files each turn	Query existing session	90%+

---

Table of Contents

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

---

Installation

Prerequisites

Requirement	Version	Installation
Node.js	v18+ (v16 minimum)	nodejs.org
Gemini CLI	Latest	npm install -g @google/gemini-cli
Google Account	-	Required for Gemini authentication

Quick Install

For Claude Code (CLI):

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

For Claude Desktop:

Add to your MCP configuration file:

Platform	Configuration File Location
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

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

Platform-Specific Instructions

Linux / macOS

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.

Windows

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.

Verify Installation

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"

---

Token Savings Examples

Example 1: Codebase Analysis

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:

Query	Traditional	With Gemini MCP	Savings
First analysis	62,000	1,700	97%
Follow-up #1	62,000	650	99%
Follow-up #2	62,000	650	99%
Follow-up #3	62,000	650	99%
Total (4 queries)	248,000	3,650	98.5%

Example 2: Documentation Review

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.

Example 3: Multi-File Refactoring

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

---

Tools Reference

ask-gemini

The primary tool for interacting with Gemini CLI.

Parameter	Type	Default	Description
prompt	string	required	Your query. Use @filename to include files.
model	string	gemini-3-pro-preview	Model to use. Falls back to gemini-3-flash-preview on quota errors.
session_id	string/number	-	Resume a previous session by ID or index.
approval_mode	string	yolo	default, auto_edit, or yolo for autonomy control.
sandbox	boolean	false	Run in isolated sandbox environment.
include_directories	string[]	-	Additional directories to include in context.
allowed_tools	string[]	-	Whitelist specific tools Gemini can use.
output_format	string	text	text, json, or stream-json.
changeMode	boolean	false	Return edits in structured OLD/NEW format for Claude to apply.

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"

brainstorm

Creative ideation using structured frameworks.

Parameter	Type	Default	Description
prompt	string	required	The challenge or topic to brainstorm.
ideaCount	number	12	Number of ideas to generate.
methodology	string	auto	Framework: divergent, convergent, scamper, design-thinking, lateral, auto.
domain	string	-	Domain context (e.g., software, business, marketing).
constraints	string	-	Limitations or requirements to consider.
includeAnalysis	boolean	true	Include feasibility/impact ratings.

Example:

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

manage-sessions

List or delete Gemini conversation sessions.

Parameter	Type	Default	Description
action	string	list	list or delete.
session_id	string	-	Session ID to delete (required for delete action).

Example:

# List all sessions
action: "list"

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

manage-extensions

Install and manage Gemini CLI extensions.

Parameter	Type	Default	Description
action	string	required	list, install, uninstall, update, enable, disable, validate.
target	string	-	Extension name or URL.
scope	string	project	project or global.
all	boolean	-	Update all extensions (with update action).

Example:

# List installed extensions
action: "list"

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

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

ping

Test connectivity with the MCP server.

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

Help

Display Gemini CLI help information.

# No parameters needed
# Returns full Gemini CLI help text

---

Usage Examples

1. Basic File Analysis

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

2. Multi-Turn Codebase Session

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.

3. Autonomous Code Fixes

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

4. Brainstorming Session

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

5. Extension Management

"Install the Gemini security extension"

Claude calls:

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

6. Session Cleanup

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

---

Troubleshooting

General Issues

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"

Windows Troubleshooting

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
   

---

Windows Compatibility

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

The Problem

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 Solution

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;

Additional Windows Fixes

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

---

Development

Building from Source

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

Running Locally

# Build and run
npm run dev

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

Adding to Claude Code (local development)

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

Project Structure

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
    └── ...

---

Contributing

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

---

License

MIT License - see LICENSE for details.

---

Credits

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