Gemini MCP Server for Claude Code

A specialized Model Context Protocol (MCP) server that extends Claude Code's capabilities with Google's Gemini 2.5 Pro Preview, featuring a massive 1M token context window for handling large codebases and complex analysis tasks.

🎯 Purpose

This server acts as a developer assistant that augments Claude Code when you need:

• Analysis of files too large for Claude's context window
• Deep architectural reviews across multiple files
• Extended thinking and complex problem solving
• Performance analysis of large codebases
• Security audits requiring full codebase context

🚀 Quick Start for Claude Code

1. Clone the Repository

First, clone this repository to your local machine:

git clone https://github.com/BeehiveInnovations/gemini-mcp-server.git
cd gemini-mcp-server

Note the full path to this directory - you'll need it for the configuration.

2. Configure in Claude Desktop

You can access the configuration file in two ways:

• Through Claude Desktop: Open Claude Desktop → Settings → Developer → Edit Config
• Direct file access:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration, replacing the path with your actual directory path:

macOS:

{
  "mcpServers": {
    "gemini": {
      "command": "/path/to/gemini-mcp-server/run_gemini.sh",
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "gemini": {
      "command": "C:\\path\\to\\gemini-mcp-server\\run_gemini.bat",
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Important: Replace /path/to/gemini-mcp-server with the actual path where you cloned the repository.

3. Restart Claude Desktop

After adding the configuration, restart Claude Desktop. You'll see "gemini" in the MCP servers list.

4. Add to Claude Code

To make the server available in Claude Code, run:

claude mcp add-from-claude-desktop -s user

5. Start Using Natural Language

Just talk to Claude naturally:

• "Use Gemini to analyze this large file..."
• "Ask Gemini to review the architecture of these files..."
• "Have Gemini check this codebase for security issues..."

💻 Developer-Optimized Features

Automatic Developer Context

When no custom system prompt is provided, Gemini automatically operates with deep developer expertise, focusing on:

• Clean code principles
• Performance optimization
• Security best practices
• Architectural patterns
• Testing strategies
• Modern development practices

Optimized Temperature Settings

• General chat: 0.5 (balanced accuracy with some creativity)
• Code analysis: 0.2 (high precision for code review)

Large Context Window

• Handles up to 1M tokens (~4M characters)
• Perfect for analyzing entire codebases
• Maintains context across multiple large files

🛠️ Available Tools

chat

General-purpose developer conversations with Gemini.

Example uses:

"Ask Gemini about the best approach for implementing a distributed cache"
"Use Gemini to explain the tradeoffs between different authentication strategies"

analyze_code

Specialized tool for analyzing large files or multiple files that exceed Claude's limits.

Example uses:

"Use Gemini to analyze /src/core/engine.py and identify performance bottlenecks"
"Have Gemini review these files together: auth.py, users.py, permissions.py"

list_models

Lists available Gemini models (defaults to 2.5 Pro Preview).

📋 Installation

1. Clone the repository:

   git clone https://github.com/BeehiveInnovations/gemini-mcp-server.git
   cd gemini-mcp-server
   

2. Create virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Set your Gemini API key:

   export GEMINI_API_KEY="your-api-key-here"
   

🔧 Advanced Configuration

Custom System Prompts

Override the default developer prompt when needed:

{
  "prompt": "Review this code",
  "system_prompt": "You are a security expert. Focus only on vulnerabilities."
}

Temperature Control

Adjust for your use case:

• 0.1-0.3: Maximum precision (debugging, security analysis)
• 0.4-0.6: Balanced (general development tasks)
• 0.7-0.9: Creative solutions (architecture design, brainstorming)

Model Selection

While defaulting to gemini-2.5-pro-preview-06-05, you can specify other models:

• gemini-1.5-pro-latest: Stable alternative
• gemini-1.5-flash: Faster responses
• Use list_models to see all available options

🎯 Claude Code Integration Examples

When Claude hits token limits:

Claude: "This file is too large for me to analyze fully..."
You: "Use Gemini to analyze the entire file and identify the main components"

For architecture reviews:

You: "Use Gemini to analyze all files in /src/core/ and create an architecture diagram"

For performance optimization:

You: "Have Gemini profile this codebase and suggest the top 5 performance improvements"

💡 Practical Usage Tips

Effective Commands

Be specific about what you want from Gemini:

• ✅ "Ask Gemini to identify memory leaks in this code"
• ❌ "Ask Gemini about this"

Common Workflows

1. Claude's Extended Thinking + Gemini Validation

You: "Design a distributed task queue system"
Claude: [provides detailed architecture and implementation plan]
You: "Share your complete design with Gemini and ask it to identify potential race conditions or failure modes"
Gemini: [analyzes and finds edge cases]
You: "Address the issues Gemini found"
Claude: [updates design with safeguards]

2. Large File Analysis

"Use Gemini to analyze /path/to/large/file.py and summarize its architecture"
"Have Gemini trace all function calls in this module"
"Ask Gemini to identify unused code in this file"

3. Multi-File Context

"Use Gemini to analyze how auth.py, users.py, and permissions.py work together"
"Have Gemini map the data flow between these components"
"Ask Gemini to find all circular dependencies in /src"

4. Claude-Driven Design with Gemini Validation

Claude: "I've designed a caching strategy using Redis with TTL-based expiration..."
You: "Share my caching design with Gemini and ask for edge cases I might have missed"

Claude: "Here's my implementation plan for the authentication system: [detailed plan]"
You: "Use Gemini to analyze this plan and identify security vulnerabilities or scalability issues"

Claude: "I'm thinking of using this approach for the data pipeline: [approach details]"
You: "Have Gemini review my approach and check these 10 files for compatibility issues"

5. Security & Performance Audits

"Use Gemini to security audit this authentication flow"
"Have Gemini identify performance bottlenecks in this codebase"
"Ask Gemini to check for common security vulnerabilities"

Best Practices

• Let Claude do the primary thinking and design work
• Use Gemini as a validation layer for edge cases and extended context
• Share Claude's complete thoughts with Gemini for comprehensive review
• Have Gemini analyze files that are too large for Claude
• Use the feedback loop: Claude designs → Gemini validates → Claude refines

Real-World Example Flow

1. You: "Create a microservices architecture for our e-commerce platform"
2. Claude: [Designs comprehensive architecture with service boundaries, APIs, data flow]
3. You: "Take my complete architecture design and have Gemini analyze it for:
   - Potential bottlenecks
   - Missing error handling
   - Security vulnerabilities
   - Scalability concerns"
4. Gemini: [Provides detailed analysis with specific concerns]
5. You: "Based on Gemini's analysis, update the architecture"
6. Claude: [Refines design addressing all concerns]

📝 Notes

• Gemini 2.5 Pro Preview may occasionally block certain prompts due to safety filters
• The server automatically falls back gracefully when this happens
• Token estimation: ~4 characters per token
• All file paths should be absolute paths

🧪 Testing

Running Tests Locally

# Install development dependencies
pip install -r requirements.txt

# Run tests with coverage
pytest

# Run tests with verbose output
pytest -v

# Run specific test file
pytest tests/test_gemini_server.py

# Generate HTML coverage report
pytest --cov-report=html
open htmlcov/index.html  # View coverage report

Continuous Integration

This project uses GitHub Actions for automated testing:

• Tests run on every push and pull request
• Supports Python 3.8 - 3.12
• Tests on Ubuntu, macOS, and Windows
• Includes linting with flake8, black, isort, and mypy
• Maintains 80%+ code coverage

🤝 Contributing

This server is designed specifically for Claude Code users. Contributions that enhance the developer experience are welcome!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (pytest)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

MIT License - feel free to customize for your development workflow.