Gemini CLI MCP Server

🚀 Token-efficient AI operations using Gemini's massive 1M token context window

A production-grade Model Context Protocol (MCP) server that wraps the Gemini CLI, enabling AI tools like Claude Code, Cursor, and Claude Desktop to leverage Gemini's large context window and free tier for cost-effective operations.

✨ Features

• 🎯 Large Context Window: Leverage Gemini's 1M token context for analyzing entire codebases
• 💰 Token Efficient: Use Gemini's free tier (1,000 requests/day) to save on API costs
• 🔧 Four Powerful Tools:
  • gemini_query: Direct queries to Gemini models
  • gemini_context_query: Queries with large context support
  • gemini_analyze_codebase: Full repository/codebase analysis
  • gemini_code_review: Adversarial code review with critic capabilities
• 🏗️ Senior Staff Engineering: Built following SOLID principles and best practices
• ⚡ Async-First: Non-blocking async subprocess execution
• 📊 Observability: Structured logging with comprehensive error handling
• 🧪 Production-Ready: Type-safe, fully tested, and battle-hardened

🚀 Quick Start

Prerequisites

Install the Gemini CLI and authenticate:

npm install -g @google/gemini-cli
gemini config  # Follow authentication prompts

Installation

One-line setup for Claude Code:

claude mcp add gemini-mcp -- uvx --from gemini-cli-mcp-tool gemini-mcp

That's it! Restart Claude Code and you're ready to use all four Gemini tools.

Alternative Setup Methods

{
  "mcpServers": {
    "gemini-mcp": {
      "command": "uvx",
      "args": ["--from", "gemini-cli-mcp-tool", "gemini-mcp"]
    }
  }
}

{
  "mcpServers": {
    "gemini-mcp": {
      "command": "uvx",
      "args": ["--from", "gemini-cli-mcp-tool", "gemini-mcp"]
    }
  }
}

{
  "mcpServers": {
    "gemini-mcp": {
      "command": "uvx",
      "args": ["--from", "gemini-cli-mcp-tool", "gemini-mcp"]
    }
  }
}

📚 Documentation

• Quick Start Guide - Get started in 5 minutes
• Installation Guide - Complete setup instructions
• Architecture - Technical design details
• Testing Guide - Development workflow

🛠️ Tools Reference

gemini_query

Direct queries to Gemini models for general-purpose AI assistance.

Parameters:

• prompt (string, required): The question or instruction
• model (string, optional): Model to use (default: gemini-2.5-pro)
• timeout (float, optional): Timeout in seconds (default: 120, max: 600)
• sandbox (bool, optional): Enable sandbox mode for code execution

Returns: {response: string, model: string, success: bool}

Example:

Use gemini_query to explain: "How does async/await work in Python?"

gemini_context_query

Optimized for large context queries (up to 1M tokens) - perfect for analyzing entire documents or codebases.

Parameters:

• prompt (string, required): The main question
• context (string, optional): Large context content (use this OR file_paths)
• file_paths (list[string], optional): List of file/folder paths for Gemini to read (use this OR context)
• model (string, optional): Model to use
• timeout (float, optional): Timeout in seconds (default: 240)

Returns: {response: string, model: string, success: bool, context_size: int}

Examples:

# With inline context
Use gemini_context_query with context from [large document] to answer: "What are the main themes?"

# With file paths (more efficient)
Use gemini_context_query with file_paths=["/path/to/docs"] to answer: "What are the main themes?"

gemini_analyze_codebase

Comprehensive repository/codebase analysis using Gemini's large context window.

Parameters:

• prompt (string, required): Analysis question
• codebase_content (string, optional): The codebase content to analyze (use this OR codebase_path)
• codebase_path (string, optional): Path to codebase folder for direct analysis (use this OR codebase_content)
• model (string, optional): Model to use

Returns: {analysis: string, model: string, success: bool}

Examples:

# With inline content
Use gemini_analyze_codebase to review security of [codebase content]

# With path (more efficient)
Use gemini_analyze_codebase with codebase_path="/path/to/project" to analyze: "What are the security issues?"

gemini_code_review

Adversarial code review tool with critic capabilities. Identifies logic errors, security issues, performance problems, and more.

Parameters:

• code (string, optional): The code to review (use this OR file_paths)
• file_paths (list[string], optional): List of file paths to review (use this OR code)
• context (string, optional): Additional context about the code
• review_focus (string, optional): Specific areas to focus on (e.g., "security", "performance")
• model (string, optional): Model to use

Returns: {review: string, model: string, success: bool}

Examples:

# With inline code
Use gemini_code_review to review [code] focusing on "security and logic errors"

# With file paths (more efficient)
Use gemini_code_review with file_paths=["src/main.py", "src/utils.py"] focusing on "security"

⚙️ Configuration

Optional .env file configuration:

# Gemini CLI Configuration
GEMINI_MCP_GEMINI_CLI_PATH=gemini
GEMINI_MCP_DEFAULT_MODEL=gemini-2.5-pro

# Execution Settings
GEMINI_MCP_DEFAULT_TIMEOUT=120.0
GEMINI_MCP_MAX_CONTEXT_TOKENS=1000000

# Server Settings
GEMINI_MCP_SERVER_NAME="Gemini MCP Server"
GEMINI_MCP_MASK_ERROR_DETAILS=true
GEMINI_MCP_LOG_LEVEL=INFO

# Feature Flags
GEMINI_MCP_ENABLE_SANDBOX=false
GEMINI_MCP_ENABLE_YOLO_MODE=false

See .env.example for full configuration options.

💻 Development

Setup Development Environment

git clone https://github.com/mgiovani/gemini-cli-mcp-tool.git
cd gemini-cli-mcp-tool
uv sync

Testing

# Run all tests
uv run pytest

# With coverage
uv run pytest --cov=gemini_mcp --cov-report=html

# Integration tests only
uv run pytest tests/integration/ -v

Code Quality

# Lint and format
uv run ruff check
uv run ruff format

# Type checking
uv run pyright

🔧 Troubleshooting

"gemini command not found"

npm install -g @google/gemini-cli
which gemini  # Should show path

MCP Server Not Connecting

1. Check the absolute path in your MCP configuration
2. Ensure uv is in your PATH: which uv
3. Test the server manually: uv run gemini-mcp
4. Check logs in your AI tool's console

Gemini CLI Authentication Issues

# Re-authenticate
gemini config

# Or check settings
cat ~/.gemini/settings.json

Timeout Errors

Increase timeout via environment variable:

export GEMINI_MCP_DEFAULT_TIMEOUT=300

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Standards

• Follow PEP 8 and use ruff for linting
• Add type hints to all functions
• Write tests for new features
• Update documentation as needed

📄 License

MIT License - see LICENSE for details

🙏 Acknowledgments

• FastMCP - Pythonic MCP framework
• Gemini CLI - Official Gemini CLI
• Model Context Protocol - MCP specification

💬 Support

• 🐛 Report Bug
• 💡 Request Feature
• 📧 Contact