Gemini MCP Tool DocumentationDocumentation
🏷️ 1.1.4

Appearance

Troubleshooting ​

Common issues and their solutions. Click any issue below to see the detailed solution.

Installation Issues ​

"Command not found: gemini"

Click to see solution →
The Gemini CLI is not installed or not in your PATH

Windows NPX Installation Issues

Click to see solution →
Error: unknown option "-y" when using Claude Code on Windows

"MCP server not responding"

Click to see solution →
Claude Desktop can't connect to the MCP server

Connection Issues ​

"Failed to connect to Gemini"

Click to see solution →
API connection issues or authentication problems

"Timeout errors"

Click to see solution →
Requests taking too long or timing out

"MCP error -32000: Connection closed"

Click to see solution →
Server fails to start and connection closes immediately (Claude Code)

"Gemini gets cut off" / Early Termination ​

Problem: Responses appear truncated or Claude reports "Gemini was thinking but got cut off"

Causes:

  • Large codebase analysis taking longer than expected
  • Complex operations requiring extended processing time
  • Client connection management issues

Solutions:

bash
# The tool automatically prevents timeouts with progress updates # You'll see messages like: # "🔍 Starting analysis (may take 5-15 minutes for large codebases)" # "🧠 Gemini is analyzing your request..."  # Use faster Flash model for large requests /gemini-cli:analyze -m gemini-2.5-flash @large-file.js  # Break up large analysis into smaller chunks /gemini-cli:analyze @specific-function.js explain this function

File Analysis Issues ​

"File not found" ​

  • Use absolute paths when possible
  • Check file permissions
  • Verify working directory

"Token limit exceeded" / "Response exceeds maximum allowed tokens (25000)" ​

Problem: Error shows response of 45,735 tokens even for small prompts

Root cause: Model-specific bug in gemini-2.5-pro (default model)

Working models:

  • ✅ gemini-2.5-flash - Works perfectly
  • ❌ gemini-2.5-pro - Always returns 45k+ tokens
  • ❌ gemini-2.0-flash-thinking - Model not found

Solutions:

bash
# Use Flash model (recommended) /gemini-cli:analyze -m gemini-2.5-flash "your prompt"  # For large contexts, break into smaller chunks /gemini-cli:analyze -m gemini-2.5-flash @file1.js @file2.js  # Alternative: Use Pro for larger contexts when it works /gemini-cli:analyze -m gemini-2.5-pro "brief analysis only"

Configuration Issues ​

Changes not taking effect ​

  1. Save config file
  2. Completely quit Claude Desktop
  3. Restart Claude Desktop
  4. Verify with /gemini-cli:help

Environment variables not working ​

bash
# Check current settings echo $GEMINI_MODEL echo $GOOGLE_GENERATIVE_AI_API_KEY

Configurable Timeout for Large Codebases ​

Problem: Default MCP client timeout too short for large analysis

Root Cause: Claude Desktop/Claude Code has a hard-coded timeout that cannot be overridden by environment variables.

Solution: The tool now automatically sends progress updates to prevent timeouts

bash
# The tool will automatically send progress messages like: # "🔍 Starting analysis (may take 5-15 minutes for large codebases)" # "🧠 Gemini is analyzing your request..." # "📊 Processing files and generating insights..." # "⏳ Still processing... Gemini is working on your request"

What happens during long operations:

  • Progress updates every 25 seconds during active processing
  • Backup heartbeat every 20 seconds to ensure connection stays alive
  • Clear status messages showing the tool is working
  • Automatic completion notification when done

For very large codebases (10,000+ files):

  • Consider breaking analysis into smaller chunks
  • Use more specific file patterns with @ syntax
  • Switch to gemini-2.5-flash for faster processing
 ## Debug Mode  Enable debug logging: ```json {  "mcpServers": {  "gemini-cli": {  "command": "gemini-mcp",  "env": {  "DEBUG": "true"  }  }  } }

Getting Help ​

  1. Check GitHub Issues
  2. Enable debug mode
  3. Collect error logs
  4. Open a new issue with details

Model-Specific Issues ​

Gemini-2.5-Pro Issues ​

Known problems:

  • Always returns 45,735 token responses (bug)
  • May cause "response exceeds limit" errors
  • Not recommended for file analysis

Workaround: Use Gemini Flash instead

bash
/gemini-cli:analyze -m gemini-2.5-flash "your prompt"

Model Recommendations ​

Use CaseRecommended ModelReason
File analysisgemini-2.5-flashFaster, stable responses
Code reviewgemini-2.5-flashGood balance of speed/quality
Large codebasegemini-2.5-flashBetter timeout handling
Quick questionsgemini-2.5-flashFast responses

Quick Fixes ​

Reset Everything ​

bash
# Remove and reinstall npm uninstall -g gemini-mcp-tool npm install -g gemini-mcp-tool  # Reset Gemini CLI gemini config reset gemini config set api_key YOUR_API_KEY

Test Basic Functionality ​

bash
# Test Gemini CLI gemini "Hello"  # Test MCP Tool with Flash model /gemini-cli:ping  # Test file analysis with working model /gemini-cli:analyze -m gemini-2.5-flash @README.md summarize

Platform-Specific Issues ​

Windows 11 ​

  • NPX flag issues: Use --yes instead of -y
  • Path problems: Restart terminal after Node.js installation
  • Connection issues: Ensure Windows Defender isn't blocking Node.js

macOS ​

  • Permission issues: Use sudo if npm install fails
  • Terminal restart: Required after installing dependencies

Linux ​

  • Node.js version: Install via NodeSource for latest version
  • npm permissions: Configure npm to avoid sudo usage