Gemini Code Review

PyPI version License: MIT Python MCP Gemini

🚀 AI-powered code reviews that understand your project's context and development progress

Transform your git diffs into actionable insights with contextual awareness of your project guidelines, task progress, and coding standards.

📚 Table of Contents

• Why Use This?
• Quick Start
• Available MCP Tools
• Configuration
• Key Features
• CLI Usage
• Troubleshooting
• Development

Why Use This?

• 🎯 Context-Aware Reviews: Automatically includes your CLAUDE.md guidelines and project standards
• 📊 Progress Tracking: Understands your task lists and development phases
• 🤖 AI Agent Integration: Seamless MCP integration with Claude Code and Cursor
• 🔄 Flexible Workflows: GitHub PR reviews, project analysis, or custom scopes
• ⚡ Smart Defaults: Auto-detects what to review based on your project state

🚀 Claude Code Installation

Option A: Install the MCP server to Claude Code as user-scoped MCP server:

claude mcp add-json gemini-code-review -s user '{"command":"uvx","args":["gemini-code-review-mcp"],"env":{"GEMINI_API_KEY":"your_key_here","GITHUB_TOKEN":"your_key_here"}}'

(-s user installs as user-scoped and will be available to you across all projects on your machine, and will be private to you. Omit -s user to install the as locally scoped.)

Option B: Install the MCP server to Claude Code as project-scoped MCP server:

claude mcp add-json gemini-code-review -s project /path/to/server '{"type":"stdio","command":"npx","args":["gemini-code-review"],"env":{"GEMINI_API_KEY":"your_key_here","GITHUB_TOKEN":"your_key_here"}}'

The command above creates or updates a .mcp.json file to the project root with the following structure:

{
  "mcpServers": {
    "gemini-code-review": {
      "command": "/path/to/server",
      "args": ["gemini-code-review"],
      "env": {"GEMINI_API_KEY":"your_key_here","GITHUB_TOKEN":"your_key_here"}
    }
  }
}

Get your Gemini API key: https://ai.google.dev/gemini-api/docs/api-key

Get your GitHub token: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

Docs for setting up MCP for Claude Code: https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-model-context-protocol-mcp

Troubleshooting MCP Installation

If the MCP tools aren't working:

1. Check your installation: claude mcp list
2. Verify API key is set: claude mcp get gemini-code-review
3. If API key shows empty, remove and re-add:

   claude mcp remove gemini-code-review
   claude mcp add-json gemini-code-review -s user '{"type":"stdio","command":"npx","args":["@modelcontextprotocol/server-gemini-code-review"],"env":{"GEMINI_API_KEY":"your_key_here","GITHUB_TOKEN":"your_key_here"}}'
   

   (Make sure you replace /path/to/server with the path to your server executable)
4. Always restart Claude Desktop after any MCP configuration changes

📋 Available MCP Tools

// Quick project review (uses default model: gemini-2.0-flash)
{
  tool_name: "generate_ai_code_review",
  arguments: {
    project_path: "/path/to/project"
  }
}

// With advanced model
{
  tool_name: "generate_ai_code_review",
  arguments: {
    project_path: "/path/to/project",
    model: "gemini-2.5-pro",  // Uses alias for gemini-2.5-pro-preview-06-05
    thinking_budget: 15000    // Optional: thinking tokens (when supported)
  }
}

// Analyze GitHub pull request
{
  tool_name: "generate_pr_review",
  arguments: {
    github_pr_url: "https://github.com/owner/repo/pull/123",
    thinking_budget: 20000    // Optional: thinking tokens
  }
}

// With reference documentation
{
  tool_name: "generate_pr_review",
  arguments: {
    github_pr_url: "https://github.com/owner/repo/pull/123",
    url_context: ["https://docs.api.com/v2/guidelines"]  // Optional: Reference docs for the review
  }
}

// Generate context from files and get AI response in one step
{
  tool_name: "ask_gemini",
  arguments: {
    user_instructions: "Review for security vulnerabilities and suggest fixes",
    file_selections: [
      { path: "src/auth.py" },
      { path: "src/database.py", line_ranges: [[50, 100]] }
    ],
    project_path: "/path/to/project",
    model: "gemini-2.5-pro"
  }
}

// Simple query without files
{
  tool_name: "ask_gemini",
  arguments: {
    user_instructions: "Explain the security implications of the current authentication approach",
    include_claude_memory: true  // Includes project guidelines
  }
}

Common Workflows

Quick Project Review

Human: Generate a code review for my project

Claude: I'll analyze your project and generate a comprehensive review.

[Uses generate_ai_code_review with project_path]

GitHub PR Review

Human: Review this PR: https://github.com/owner/repo/pull/123

Claude: I'll fetch the PR and analyze the changes.

[Uses generate_pr_review with github_pr_url]

Custom Model Review

Human: Generate a detailed review using Gemini 2.5 Pro

Claude: I'll use Gemini 2.5 Pro for a more detailed analysis.

[Uses generate_ai_code_review with model="gemini-2.5-pro"]

File-Specific Review with AI

Human: Review auth.py and database.py lines 50-100 for security issues

Claude: I'll analyze those specific files for security vulnerabilities.

[Uses ask_gemini with file_selections and security-focused instructions]

Quick Code Question

Human: What are the performance implications of the current caching strategy?

Claude: I'll analyze your caching implementation and provide insights.

[Uses ask_gemini with user_instructions only, leveraging project context]

⚙️ Configuration

Environment Variables

Model Configuration

Default Models

• Primary Model: gemini-2.0-flash - Fast, efficient model for code reviews
• Summary Model: gemini-2.0-flash-lite - Used internally for quick summaries

Model Aliases

For convenience, you can use these short aliases instead of full model names:

Available Models

All models support code review, with varying capabilities:

With Thinking Mode + URL Context:

• gemini-2.5-pro (alias) / gemini-2.5-pro-preview-06-05
• gemini-2.5-flash (alias) / gemini-2.5-flash-preview-05-20

With URL Context Only:

• gemini-2.0-flash (default)
• gemini-2.0-flash-live-001

Basic Models:

• gemini-1.5-pro
• gemini-1.5-flash (used for integration tests - cost-effective)

Usage Examples

// Using default model (gemini-2.0-flash)
{ tool_name: "generate_ai_code_review", arguments: { project_path: "/path" } }

// Using alias for advanced model
{ tool_name: "generate_ai_code_review", arguments: { 
  project_path: "/path",
  model: "gemini-2.5-pro"  // Automatically resolves to gemini-2.5-pro-preview-06-05
} }

// Using full model name
{ tool_name: "generate_ai_code_review", arguments: { 
  project_path: "/path",
  model: "gemini-2.5-pro-preview-06-05"
} }

Automatic Configuration Discovery

When enabled with flags, the tool discovers and includes:

• 📁 CLAUDE.md files at project/user/enterprise levels (use --include-claude-memory)
• 📝 Cursor rules (.cursorrules, .cursor/rules/*.mdc) (use --include-cursor-rules)
• 🔗 Import syntax (@path/to/file.md) for modular configs

Configuration in pyproject.toml

You can set default values in your pyproject.toml:

[tool.gemini]
temperature = 0.5
default_prompt = "Your custom review prompt"
default_model = "gemini-1.5-flash"
include_claude_memory = true
include_cursor_rules = false
enable_cache = true
cache_ttl_seconds = 900  # 15 minutes

Configuration precedence: CLI flags > Environment variables > pyproject.toml > Built-in defaults

✨ Key Features

• 🤖 Smart Context - Optionally includes CLAUDE.md (use --include-claude-memory), task lists (use --task-list), and project structure
• 🎯 Flexible Scopes - Review PRs, recent changes, or entire projects
• ⚡ Model Selection - Choose between Gemini 2.0 Flash (speed) or 2.5 Pro (depth)
• 🔄 GitHub Integration - Direct PR analysis with full context
• 📊 Progress Aware - Understands development phases and task completion
• 🔗 URL Context - Gemini automatically fetches and analyzes URLs in prompts (or use --url-context flag)
• 🏗️ Project Scaffolding - Initialize projects with recommended structure via gemini-code-review-init
• 🚀 Performance Optimized - Built-in caching layer for faster repeated operations
• 🎨 Clear Mode Indication - Explicit feedback about Task-Driven vs General Review modes

🖥️ CLI Usage

Alternative: Command-line interface for development/testing

Installation

# Quick start with uvx (no install needed)
uvx gemini-code-review-mcp /path/to/project

# Or install globally
pip install gemini-code-review-mcp

Commands

# Initialize a new project with recommended structure
gemini-code-review-init

# Basic review (current directory)
generate-code-review

# Review specific project
generate-code-review /path/to/project

# Advanced options
generate-code-review . \
  --scope full_project \
  --model gemini-2.5-pro

# Use specific task list (overrides auto-discovery)
generate-code-review \
  --task-list tasks/tasks-feature-x.md \
  --scope specific_phase \
  --phase-number 2.0

# With thinking budget (current directory)
generate-code-review --thinking-budget 20000 --temperature 0.7

# With URL context for framework-specific review
generate-code-review \
  --file-instructions "Review my async implementation against the official docs" \
  --url-context https://docs.python.org/3/library/asyncio.html

# File-based context generation (for debugging - does not call AI)
generate-file-context -f src/main.py -f src/utils.py:10-50 \
  --user-instructions "Review for performance issues" \
  -o context.md

# Meta-prompt only (current directory)
generate-meta-prompt --stream

Review Modes

The tool operates in one of three modes:

1. 🔍 General Review Mode: Default mode (no --task-list flag)

   • Comprehensive code quality analysis
   • Focuses on best practices and improvements
   • Best for: Maintenance, refactoring, or exploratory reviews

2. 📝 Task-Driven Mode: When --task-list flag is used (opt-in)

   • Enable with: generate-code-review . --task-list tasks-feature.md
   • Or auto-select latest: generate-code-review . --task-list
   • Contextualizes review based on your current development phase
   • Tracks progress against planned tasks
   • Best for: Active development with defined milestones

3. 🐙 GitHub PR Mode: When --github-pr-url is provided

   • Analyzes specific pull request changes
   • Includes PR context and discussions
   • Best for: Code review workflows

Supported File Formats

• 📋 Task Lists: /tasks/tasks-*.md - Track development phases
• 📄 PRDs: /tasks/prd-*.md - Project requirements
• 📦 Configs: CLAUDE.md, .cursorrules - Coding standards

🆘 Troubleshooting

• Missing API key? → Get one at ai.google.dev
• MCP not working? → Run claude mcp list to verify installation
• Old version cached? → Run uv cache clean

📦 Development

# Setup
git clone https://github.com/nicobailon/gemini-code-review-mcp
cd gemini-code-review-mcp
pip install -e ".[dev]"

# Testing commands
python -m pytest tests/    # Run all tests in venv
make lint                  # Check code style
make test-cli             # Test CLI commands

Testing Configuration

The test suite includes both mocked unit tests and real API integration tests:

Unit Tests (Default)

• Fast execution: Mock all external API calls
• No API key required: Run without any setup
• Model configuration: Tests use gemini-2.0-flash defaults
• Run with: pytest or python -m pytest tests/

Integration Tests (Optional)

• Real API calls: Uses gemini-1.5-flash for cost-effective testing
• API key required: Set GEMINI_API_KEY environment variable
• Limited features: Tests only features supported by gemini-1.5-flash (no thinking mode/URL context)
• Run with: pytest -m integration or pytest tests/integration/

Running Tests

# Run only unit tests (default, fast)
pytest

# Run only integration tests (requires API key)
export GEMINI_API_KEY=your_key_here
pytest -m integration

# Run all tests including integration
pytest -m ""

# Run specific integration test
pytest tests/integration/test_gemini_real.py::TestGeminiRealAPI::test_basic_code_review_generation

# Verbose output with integration tests
pytest -v -m integration

Test Features

• Model verification: Ensures gemini-1.5-flash is used for integration tests
• Capability testing: Validates that unsupported features are properly handled
• Error handling: Tests graceful degradation with invalid inputs
• Temperature testing: Verifies model parameter effects

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. See CONTRIBUTING.md for development setup and guidelines.

Release Process

This project uses a manual release process. For maintainers:

• Run ./scripts/check-release-readiness.sh to verify readiness
• Follow MANUAL_RELEASE_GUIDE.md for detailed steps
• Or use ./scripts/release.sh for guided release process

📏 License

MIT License - see LICENSE file for details.

👥 Credits

Built by Nico Bailon.