kousen/GeminiMcpServer

Gemini MCP Server

A Spring Boot-based Model Context Protocol (MCP) server that enables MCP clients to leverage Google Gemini's large context window for codebase analysis. This server acts as a bridge between MCP clients (like Claude Desktop, Cursor, or Claude Code) and Google Gemini, allowing you to offload large codebase analysis tasks to Gemini while preserving your primary assistant's context window.

Overview

This MCP server provides two main tools:

• gemini_scanAndPlan: Scans a codebase and creates an analysis plan, with support for file filtering, size limits, and automatic sharding for large projects
• gemini_analyzeCodebase: Executes codebase analysis using the Gemini CLI with the scanned files

Key Features

• 🎯 Smart File Selection: Include/exclude patterns for precise file filtering
• 📦 Automatic Sharding: Splits large codebases into manageable chunks (though rarely needed with Gemini's 1M+ token context)
• 🚫 Binary File Detection: Automatically skips binary files to avoid token waste
• 📊 Size Management: Configurable file and byte limits
• 🔧 Spring Boot Integration: Built on Spring AI's MCP server framework
• ✅ Comprehensive Testing: Full test coverage with unit and integration tests
• 🚀 Gemini 2.5 Flash: Always uses gemini-2.5-flash model for maximum context (1M tokens)
• 📁 Context Inclusion: Uses Gemini CLI's -a flag to include all project files in analysis

Prerequisites

• Java 21 or higher
• Google Gemini CLI installed (gemini command available in PATH)
• Gemini API key configured (set via environment variable or Gemini CLI config)

Installing Gemini CLI

# For macOS with Homebrew:
brew install gemini

# Verify installation:
which gemini  # Should show /opt/homebrew/bin/gemini or similar
gemini --version

# Configure your API key (if not already done):
export GEMINI_API_KEY="your-api-key-here"

Installation

1. Clone the repository:

git clone <repository-url>
cd GeminiMcpServer

2. Build the project:

./gradlew build

3. Run tests to verify everything works:

./gradlew test

Configuration

Building the Server

Important: You don't need to run the server manually! MCP clients will automatically start and manage the server process. You only need to build it:

# Build the executable JAR (this is all you need to do!)
./gradlew bootJar

# The JAR will be created at: build/libs/GeminiMcpServer-0.0.1-SNAPSHOT.jar

The commands below are only for testing/debugging purposes:

# For testing: Run via Gradle
./gradlew bootRun

# For testing: Run the JAR directly
java -jar build/libs/GeminiMcpServer-0.0.1-SNAPSHOT.jar

MCP Client Configuration

Once you've built the JAR, configure your MCP client to use it. The client will handle starting and stopping the server automatically.

Claude Desktop / Cursor

Add the following to your Claude Desktop or Cursor MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gemini-analyzer": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/GeminiMcpServer/build/libs/GeminiMcpServer-0.0.1-SNAPSHOT.jar"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"  // Optional if configured in Gemini CLI
      }
    }
  }
}

Claude Code

You can add the MCP server to Claude Code in two ways:

Option 1: Via Command Line (Recommended)

# Add to current project only (stored in .claude/)
claude mcp add gemini-analyzer -- java -jar /path/to/GeminiMcpServer/build/libs/GeminiMcpServer-0.0.1-SNAPSHOT.jar

# Or add to project and commit to version control
claude mcp add gemini-analyzer --scope project -- java -jar /path/to/GeminiMcpServer/build/libs/GeminiMcpServer-0.0.1-SNAPSHOT.jar

# Or add globally for all projects
claude mcp add gemini-analyzer --scope user -- java -jar /path/to/GeminiMcpServer/build/libs/GeminiMcpServer-0.0.1-SNAPSHOT.jar

Option 2: Manual Configuration

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "gemini-analyzer": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/GeminiMcpServer/build/libs/GeminiMcpServer-0.0.1-SNAPSHOT.jar"
      ],
      "env": {}
    }
  }
}

Note: Make sure the Gemini API key is available in your environment when running Claude Code. Project-scoped servers (in .mcp.json) will require user approval on first use.

Alternative: Using Gradle Wrapper

You can also run the server directly using the Gradle wrapper:

{
  "mcpServers": {
    "gemini-analyzer": {
      "command": "/path/to/GeminiMcpServer/gradlew",
      "args": ["bootRun"],
      "cwd": "/path/to/GeminiMcpServer"
    }
  }
}

Usage

Subagent Pattern (Recommended)

This MCP server is designed to work best as part of a Claude Code subagent workflow:

1. Create a subagent in Claude Code that includes this MCP server
2. Invoke the subagent with prompts like "Ask Gemini to analyze this codebase"
3. Results are saved to a file in the project directory: gemini-analysis-<timestamp>.md
4. Claude Code reads the file after Gemini completes the analysis

Example Subagent Configuration:

name: gemini-analyzer
description: Analyzes codebases using Google Gemini's large context window
mcp_servers:
  - gemini-analyzer
instructions: |
  When asked to analyze a codebase:
  1. Use gemini_scanAndPlan to scan the files
  2. Use gemini_analyzeCodebase to run the analysis
  3. Report the output file path back to the user
  4. The analysis will be saved to gemini-analysis-<timestamp>.md

Direct Usage

The MCP server provides two tools that can be invoked by your AI assistant:

1. Scan and Plan Analysis

// The assistant can call this tool to scan a codebase
gemini_scanAndPlan({
  root: "/path/to/project",           // Required: project root directory
  includePatterns: ["**/*.java"],     // Optional: glob patterns to include
  excludePatterns: ["**/test/**"],    // Optional: glob patterns to exclude  
  maxFiles: 1000,                     // Optional: maximum files to include
  maxBytes: 10485760,                 // Optional: maximum total bytes
  targetTokens: 900000                // Optional: target tokens per shard
})

2. Analyze Codebase

// The assistant can call this tool to analyze the scanned files
// Results are saved to: <root>/gemini-analysis-<timestamp>.md
gemini_analyzeCodebase({
  root: "/path/to/project",
  model: "gemini-2.5-flash",                   // Optional: Gemini model to use (default)
  strategy: "MAP_REDUCE",                      // Optional: analysis strategy
  includePatterns: ["**/*.java"],              // Optional: file patterns
  prompt: "Analyze this codebase for security vulnerabilities"
})

// Returns:
{
  "format": "markdown",
  "report": "...",                             // The full analysis report
  "outputFile": "/path/to/project/gemini-analysis-20250106-143022.md",
  "stats": { ... }
}

Example Use Cases

In Claude Code or Claude Desktop

1. Large Codebase Review:

   User: "Can you have Gemini analyze this entire Spring Boot application for architectural improvements?"
   Assistant: [Uses gemini_scanAndPlan to scan the codebase, then gemini_analyzeCodebase to get Gemini's analysis]
   

2. Security Audit:

   User: "Ask Gemini to review all our Java files for security vulnerabilities"
   Assistant: [Scans for *.java files and sends them to Gemini for security analysis]
   

3. Code Quality Assessment:

   User: "Get Gemini's opinion on our test coverage and testing patterns"
   Assistant: [Scans test directories and sends to Gemini for test quality analysis]
   

Architecture

┌─────────────┐     MCP      ┌──────────────┐     CLI      ┌─────────┐
│   Claude    │◄────────────►│  This MCP    │◄────────────►│ Gemini  │
│   Desktop/  │   Protocol    │   Server     │   Execution  │   CLI   │
│   Code      │               │ (Spring Boot)│              │         │
└─────────────┘               └──────────────┘              └─────────┘

Token Context Windows

• Gemini 2.5 Flash: 1 million tokens (default model)
• Gemini 2.5 Pro: 2 million tokens
• Claude 3.5 Sonnet: 200k tokens
• GPT-4 Turbo: 128k tokens

This significant difference in context window size makes Gemini ideal for whole-codebase analysis tasks.

Development

Project Structure

GeminiMcpServer/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── edu/trincoll/geminimcpserver/
│   │   │       ├── GeminiMcpServerApplication.java  # Spring Boot main
│   │   │       └── GeminiTools.java                 # MCP tool implementations
│   │   └── resources/
│   │       └── application.properties               # Spring configuration
│   └── test/
│       └── java/
│           └── edu/trincoll/geminimcpserver/
│               ├── GeminiToolsTest.java             # Unit tests
│               ├── GeminiToolsAdvancedTest.java     # Advanced scenarios
│               ├── GeminiMcpServerIntegrationTest.java # Integration tests
│               └── TestFixtures.java                # Test utilities
├── build.gradle.kts                                 # Gradle build configuration
└── README.md                                        # This file

Running Tests

# Run all tests
./gradlew test

# Run specific test class
./gradlew test --tests GeminiToolsTest

# Run with detailed output
./gradlew test --info

Building

# Build the project
./gradlew build

# Build executable JAR
./gradlew bootJar

# Clean and rebuild
./gradlew clean build

Logs and Output

Log Files

The server creates detailed logs to help with debugging:

• Console output: Shows key operations with timestamps
• Log file: gemini-mcp-server.log in the working directory
• Log level: DEBUG for the Gemini tools, INFO for Spring components

Analysis Output Files

Each analysis creates a timestamped markdown file:

• Location: In the analyzed project's root directory
• Format: gemini-analysis-YYYYMMDD-HHmmss.md
• Content: Complete Gemini analysis report in markdown format

Example output files:

/your/project/
├── src/
├── build.gradle.kts
├── gemini-analysis-20250106-143022.md  # First analysis
└── gemini-analysis-20250106-151545.md  # Second analysis

Troubleshooting

Common Issues

1. Gemini CLI not found: Ensure gemini is in your PATH

   which gemini  # Should return /opt/homebrew/bin/gemini or similar
   

   • On M1/M2 Macs, Gemini is typically installed at /opt/homebrew/bin/gemini
   • The MCP server automatically adds this to PATH when running

2. Empty or minimal analysis results:

   • Check the log file (gemini-mcp-server.log) for "Command succeeded with X chars of output"
   • If X is very small (1-2 chars), Gemini isn't receiving the context properly
   • The server uses the -a flag to include all files - ensure you're running from the project root

3. "Broken pipe" errors:

   • Usually means the Gemini CLI rejected the input format
   • Check that gemini CLI is up to date: gemini --version
   • The server now uses --prompt flag instead of piping content via stdin

4. API Key issues: Set the GEMINI_API_KEY environment variable

   export GEMINI_API_KEY="your-key-here"
   

5. Java version: Ensure you're using Java 21+

   java -version  # Should show version 21 or higher
   

6. Wrong Gemini model: The server forces gemini-2.5-flash regardless of what the client requests

   • This ensures maximum context window (1M tokens)
   • Check logs to confirm: should show "gemini --model gemini-2.5-flash"

7. MCP client can't connect: Check that the path in config is absolute and correct

   # Test the JAR directly:
   java -jar /path/to/GeminiMcpServer-0.0.1-SNAPSHOT.jar
   

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License - see file for details

Acknowledgments

• Built with Spring AI MCP Server
• Powered by Google Gemini
• Designed for use with Claude and other MCP clients