Gemini CLI MCP server

This Model Context Protocol (MCP) server integrates Gemini CLI with Claude Code, enabling comprehensive codebase analysis. It leverages Gemini's 1M token context window and code2prompt for efficient context extraction, providing both full-system architecture reviews and targeted component analysis.

Prerequisites

Required Tools

• Node.js 18+ - For running the MCP server
• Gemini CLI - Google's CLI tool with OAuth authentication
• code2prompt - Rust CLI tool for codebase extraction
• Claude Code - For sub-agent integration

Installation

Install Gemini CLI

npm install -g @google/gemini-cli

Authenticate with your Google account:

gemini
# Follow OAuth setup prompts

Install code2prompt

# macOS/Linux with Homebrew
brew install mufeedvh/tap/code2prompt

# Or build from source
cargo install code2prompt

Install MCP Server Dependencies

cd /Users/ryangould/Dev/gemini-cli-mcp
npm install

Setup & Configuration

Build the MCP Server

npm run build

Configure Claude Code MCP Settings

Add to your Claude Code MCP settings (usually ~/.config/claude-desktop/mcp_settings.json):

{
  "mcpServers": {
    "gemini-cli-mcp": {
      "command": "node",
      "args": [
        "/Users/ryangould/Dev/gemini-cli-mcp/dist/server.js"
      ],
      "env": {}
    }
  }
}

Restart Claude Code

Restart Claude Code to load the new MCP server.

Available Tools

gemini_comprehensive_review

Performs a complete codebase architectural review using Gemini CLI.

Parameters:

• workingDir (string): Path to the codebase directory
• excludePatterns (array, optional): Additional patterns to exclude

Usage Example:

// Called by Claude Code sub-agent
gemini_comprehensive_review({
  workingDir: "/path/to/your/project"
})

gemini_targeted_analysis

Analyzes specific files or folders with focused insights.

Parameters:

• workingDir (string): Path to the codebase directory
• targetPaths (array): Specific files/folders to analyze
• analysisContext (string, optional): Additional context for the analysis

Usage Example:

// Called by Claude Code sub-agent
gemini_targeted_analysis({
  workingDir: "/path/to/your/project",
  targetPaths: ["src/api/", "src/controllers/auth.js"],
  analysisContext: "Security review of authentication components"
})

Claude Code Integration

Sub-Agent Usage

The gemini-code-analyzer sub-agent is automatically available in Claude Code once the MCP server is configured.

Example Commands:

• "Please analyze this entire codebase for architectural issues"
• "Review the authentication module in src/auth/ for security vulnerabilities"
• "Analyze the API endpoints in src/controllers/ for performance bottlenecks"

Manual Tool Access

You can also call the MCP tools directly through Claude Code's tool interface:

• Use /tools to see available MCP tools
• Select gemini_comprehensive_review or gemini_targeted_analysis
• Provide required parameters

Troubleshooting

Common Issues

"gemini command not found"

Ensure Gemini CLI is installed and in your PATH:

gemini
# Follow OAuth setup prompts

"code2prompt command not found"

Install code2prompt:

brew install mufeedvh/tap/code2prompt

Authentication Issues

Re-authenticate with Gemini CLI:

gemini
# Follow OAuth setup prompts

MCP Server Not Connecting

• Check Claude Code MCP settings configuration
• Verify the server path is correct
• Check console logs for errors
• Restart Claude Code after configuration changes

Logging

The MCP server logs to stderr. Monitor logs when running:

npm run dev

Configuration Options

Excluding Files/Patterns

The comprehensive review automatically excludes common patterns:

• node_modules/**
• .git/**
• *.log
• dist/, build/
• .next/**
• coverage/**

Add custom exclusions via the excludePatterns parameter.

Token Management

• code2prompt provides token counting for large codebases
• Gemini CLI handles the 1M token context window automatically
• Large codebases are efficiently processed through code2prompt's optimization

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "gemini-cli-mcp" '{"command":"node","args":["/Users/ryangould/Dev/gemini-cli-mcp/dist/server.js"],"env":[]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "gemini-cli-mcp": {
            "command": "node",
            "args": [
                "/Users/ryangould/Dev/gemini-cli-mcp/dist/server.js"
            ],
            "env": []
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your 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

2. Add this to your configuration file:

{
    "mcpServers": {
        "gemini-cli-mcp": {
            "command": "node",
            "args": [
                "/Users/ryangould/Dev/gemini-cli-mcp/dist/server.js"
            ],
            "env": []
        }
    }
}

3. Restart Claude Desktop for the changes to take effect