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 gl

... [View full README on GitHub](https://github.com/kousen/GeminiMcpServer#readme)