Gemini Code Reviewer

A universal Model Context Protocol (MCP) server that provides AI-powered code review and analysis for any programming language using Google's Gemini CLI. Perfect for developers who want intelligent code feedback directly in their development workflow.

🎯 Purpose

This MCP server acts as your AI-powered code reviewer, providing:

• Comprehensive Code Reviews with severity ratings and actionable feedback
• Code Analysis & Explanation for understanding complex logic
• Improvement Suggestions tailored to your specific goals with clear code examples
• Architecture Validation for design patterns and scalability
• Multi-Language Support with language-specific best practices
• Structured Output - Clear explanations with formatted code suggestions

🚀 Quick Start

Prerequisites

• Node.js v18+
• Gemini CLI installed and configured
• Claude Code CLI or Claude Desktop
• Any Unix-like environment (Linux, macOS, WSL)

Installation

# Install as project dependency
npm install --save-dev github:iamrichardd/claude-gemini-mcp-server

# Add MCP server to Claude CLI
claude mcp add -s project gemini-code-reviewer npx @iamrichardd/claude-gemini-mcp-server

# Initialize and approve the MCP server
claude init
# Choose option 1: "Use this and all future MCP servers in this project"

Important Note on Context Files: This package includes GEMINI.md and CLAUDE.md files that provide context for its own development. To prevent these files from interfering with the context of your project, a postinstall script will automatically remove them upon installation. This ensures that the Gemini and Claude CLIs use your project's specific context files, not the ones from this server.

Verify Installation

# Check if MCP server is registered and connected
claude mcp list
# Should show: gemini-code-reviewer ✓ connected

# Test basic functionality
claude "Use get_review_history"

📋 Available Tools

Tool	Description	Best For
gemini_code_review	Comprehensive code review with ratings and priorities	Code quality, bug detection, best practices
gemini_analyze_code	Deep code analysis and explanation	Understanding complex code, optimization
gemini_suggest_improvements	Specific improvement recommendations with code examples	Refactoring, performance, maintainability
gemini_validate_architecture	Architecture and design pattern validation	System design, scalability, SOLID principles
gemini_propose_plan	Generate structured implementation plans for other AIs to follow	Task planning, workflow design, AI collaboration
get_review_history	Session history and review tracking	Project overview, progress tracking

🌍 Supported Languages

Auto-detected support for 30+ languages:

Web Development

• JavaScript, TypeScript, HTML, CSS, SCSS, Sass
• React (JSX/TSX), Vue.js, Angular

Backend & Systems

• Python, Java, C++, C, C#, Go, Rust
• PHP, Ruby, Node.js, Kotlin, Swift

Data & Analytics

• R, SQL, MATLAB, Python (NumPy/Pandas)

Mobile Development

• Swift (iOS), Kotlin (Android), Dart (Flutter)

Functional & Specialized

• Haskell, Clojure, OCaml, Elixir, Erlang, Scala

Scripting & Configuration

• Shell, Bash, PowerShell, Perl, Lua, Vim script

Financial & Trading

• Pine Script (TradingView indicators/strategies)

Language detection is automatic based on file extension. Manual specification is also supported.

💡 Usage Examples

Comprehensive Code Review

claude "Use gemini_code_review with file_path './src/api.js' and context 'REST API endpoint' and focus_areas 'security'"
# Get detailed security review with specific recommendations

Code Analysis & Explanation

claude "Use gemini_analyze_code with file_path './algorithm.py' and analysis_type 'optimize'"

Get Improvement Suggestions

claude "Use gemini_suggest_improvements with file_path './component.tsx' and improvement_goals 'performance'"
# Get specific performance improvements with code examples

Architecture Validation

claude "Use gemini_validate_architecture with file_path './service.go' and validation_focus 'scalability'"

Review Session Tracking

claude "Use get_review_history"

AI Collaboration Planning

claude "Use gemini_propose_plan with prompt 'Create a user authentication system with JWT tokens'"
# Get a structured plan that Claude can then execute step by step

📝 Code Suggestions Format

When Gemini identifies specific code improvements, you'll receive:

Structured Response Format

💡 Gemini Improvement Suggestion - api.js (JavaScript)

**Rationale:**
This code uses nested callbacks which can lead to callback hell. Converting to async/await will improve readability and error handling.

**Suggested Code Change:**

Old Code:
```javascript
getData(callback) {
  db.query('SELECT * FROM users', (err, result) => {
    if (err) callback(err);
    else callback(null, result);
  });
}

New Code: ```javascript async getData() { try { const result = await db.query('SELECT * FROM users'); return result; } catch (err) { throw err; } } ```

Features

• Clear Explanations: Detailed rationale for each suggestion
• Formatted Code: Properly highlighted old and new code blocks
• Language-Specific: Tailored to your programming language's conventions
• Copy-Paste Ready: Well-formatted code for easy implementation

🔧 Configuration

Claude CLI MCP Setup

The MCP server integrates with Claude CLI using project-level configuration:

# Add MCP server to your project
claude mcp add -s project gemini-code-reviewer npx @iamrichardd/claude-gemini-mcp-server

# Initialize and approve MCP servers
claude init
# Choose option 1 for persistent approval

Manual Configuration (if needed)

Create .mcp.json in your project root:

For Production Usage (published package):

{
  "mcpServers": {
    "gemini-code-reviewer": {
      "command": "npx",
      "args": ["@iamrichardd/claude-gemini-mcp-server"],
      "transport": "stdio"
    }
  }
}

For Local Development:

{
  "mcpServers": {
    "gemini-code-reviewer": {
      "command": "node",
      "args": ["server.js"],
      "transport": "stdio"
    }
  }
}

🔍 Tool Parameters

gemini_code_review

• file_path (required): Path to source code file
• context (optional): Additional context about the code
• focus_areas (optional): syntax, logic, performance, best_practices, security, testing
• language (optional): Programming language (auto-detected if not specified)

gemini_analyze_code

• file_path (required): Path to source code file
• **Provide an AI prompt for Gemini CLI ** (optional): explain, optimize, debug, refactor, compare
• language (optional): Programming language (auto-detected)

gemini_suggest_improvements

• file_path (required): Path to source code file
• improvement_goals (optional): performance, readability, maintainability, scalability, security
• language (optional): Programming language (auto-detected)

gemini_validate_architecture

• file_path (required): Path to source code file or directory
• validation_focus (optional): architecture, design_patterns, scalability, testability, maintainability
• language (optional): Programming language (auto-detected)

gemini_propose_plan

• prompt (required): High-level user request or task description that needs a plan
• conversation_history (optional): Previous conversation context for iterative refinement of the plan

🛠️ Development Workflow

Recommended Usage Pattern

1. Implement your code using Claude Code CLI directly
2. Review using gemini_code_review for comprehensive feedback with specific recommendations
3. Analyze complex sections with gemini_analyze_code
4. Improve based on gemini_suggest_improvements recommendations with clear code examples
5. Validate overall architecture with gemini_validate_architecture
6. Track progress with get_review_history

Standard Workflow

1. Request Review/Suggestions → Server analyzes code with Gemini
2. Receive Detailed Feedback → Get explanation with formatted code suggestions
3. Review & Implement → Examine suggestions and manually apply improvements
4. Copy/Paste → Use provided code examples to implement changes
5. Iterate → Continue with next suggestions or move to validation

Integration with IDEs

Works seamlessly with:

• Claude Code CLI (primary integration)
• Claude Desktop (alternative setup)
• WebStorm/IntelliJ (via Claude Code plugin)
• VS Code (via Claude Code integration)

🚨 Troubleshooting

MCP Server Not Found

# Check installation
npm list | grep claude-gemini-mcp-server

# Reinstall if needed
npm install --save-dev github:iamrichardd/claude-gemini-mcp-server
claude mcp add -s project gemini-code-reviewer npx @iamrichardd/claude-gemini-mcp-server
claude init

MCP Server Connection Hanging

If commands like claude "Use get_review_history" hang or timeout:

# For local development, use local server instead of npm package
claude mcp add -s project gemini-code-reviewer node server.js
claude init

# Verify server starts locally
node server.js
# Should show: "Gemini Code Review MCP Server (Security-Hardened v2.1.1) running on stdio"

# Check .mcp.json uses correct configuration
cat .mcp.json
# For local dev: should use "command": "node", "args": ["server.js"]
# For published package: should use "command": "npx", "args": ["@iamrichardd/claude-gemini-mcp-server"]

Gemini CLI Issues

# Test Gemini CLI directly
gemini -p "test prompt"

# Verify authentication and availability
gemini --version

# Check if Gemini CLI is in PATH
which gemini

Permission Issues

# Ensure MCP server is approved
claude init
# Choose option 1: "Use this and all future MCP servers in this project"

# Check MCP server status
claude mcp list
# Should show: gemini-code-reviewer ✓ connected

Binary File Errors

# The server automatically detects and rejects binary files
# Error: "File appears to be binary, not a text-based source code file"
# Solution: Ensure you're pointing to text-based source code files only

Language Detection Issues

# Manually specify language if auto-detection fails
claude "Use gemini_code_review with file_path './script' and language 'Python'"

Server Execution Issues

# Verify server starts correctly
npx @iamrichardd/claude-gemini-mcp-server
# Should show: "Gemini Code Review MCP Server (Security-Hardened v2.0.7) running on stdio"

# Check file permissions
chmod +x node_modules/@iamrichardd/claude-gemini-mcp-server/server.js

Error Stack Trace Issues

# The server preserves complete error context for debugging
# Check logs for detailed error information including:
# - Original error message and stack trace
# - Operation context (file path, operation type)
# - Error cause chain for complete debugging context

🤝 Contributing

Contributions welcome! Please see our Contributing Guidelines for details.

Development Setup

git clone https://github.com/iamrichardd/claude-gemini-mcp-server.git
cd claude-gemini-mcp-server
npm install

# Configure MCP server for local development
claude mcp add -s project gemini-code-reviewer node server.js

# Initialize and approve the MCP server
claude init
# Choose option 1: "Use this and all future MCP servers in this project"

# Start development server
npm run dev

Local Development Configuration

For local development, use the local server instead of the npm package:

{
  "mcpServers": {
    "gemini-code-reviewer": {
      "command": "node",
      "args": ["server.js"],
      "transport": "stdio"
    }
  }
}

📄 License

MIT License - see LICENSE file for details.

🔗 Related Tools

• Gemini CLI - Google's AI CLI tool
• Claude Code CLI - Anthropic's AI development assistant
• Model Context Protocol - Standard for AI tool integration

📊 Use Cases

For Individual Developers

• Code Quality Assurance: Automated reviews before commits
• Learning Tool: Understand complex codebases and patterns
• Performance Optimization: Identify bottlenecks and improvements
• Best Practices: Language-specific recommendations

For Teams

• Code Review Automation: Pre-review screening and feedback
• Architecture Validation: Ensure design consistency
• Onboarding: Help new team members understand code
• Documentation: Generate explanations for complex logic

For Specific Domains

• Web Development: Security, performance, accessibility reviews
• Backend Systems: Scalability, reliability, architecture validation
• Data Science: Algorithm optimization, code clarity
• Mobile Development: Platform-specific best practices
• Financial/Trading: Pine Script strategy validation and optimization

---

Powered by Google Gemini AI | Compatible with Claude Code | Universal Language Support