Gemini CLI MCP Server
A Model Context Protocol (MCP) server that integrates Gemini CLI with Claude Code for comprehensive codebase analysis using code2prompt.
Features
- Comprehensive Codebase Review: Full architectural analysis using Gemini's 1M token context window
- Targeted Component Analysis: Focused analysis on specific files/folders
- Code2Prompt Integration: Efficient codebase context extraction with token optimization
- OAuth Support: Works with your existing Gemini CLI OAuth authentication
- Claude Code Sub-Agent: Specialized agent for intelligent analysis orchestration
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 Steps
1. Install Gemini CLI
npm install -g @google/gemini-cli
Authenticate with your Google account:
gemini
# Follow OAuth setup prompts
2. Install code2prompt
# macOS/Linux with Homebrew
brew install mufeedvh/tap/code2prompt
# Or build from source
cargo install code2prompt
3. Install MCP Server Dependencies
cd /Users/ryangould/Dev/gemini-cli-mcp
npm install
Setup & Configuration
1. Build the MCP Server
npm run build
2. 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": {}
}
}
}
3. 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 directoryexcludePatterns(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 directorytargetPaths(array): Specific files/folders to analyzeanalysisContext(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
/toolsto see available MCP tools - Select
gemini_comprehensive_revieworgemini_targeted_analysis - Provide required parameters
Development
Running in Development Mode
npm run dev
Building for Production
npm run build
npm start
Project Structure
gemini-cli-mcp/
├── src/
│ ├── server.ts # Main MCP server
│ ├── tools/ # MCP tool implementations
│ │ ├── comprehensive-review.ts
│ │ └── targeted-analysis.ts
│ └── utils/ # Utility functions
│ ├── code2prompt-executor.ts
│ └── gemini-executor.ts
├── prompts/ # Prompt templates
│ ├── comprehensive-review.md
│ └── targeted-analysis.md
├── dist/ # Built TypeScript output
└── package.json
Troubleshooting
Common Issues
"gemini command not found"
Ensure Gemini CLI is installed and in your PATH:
npm install -g @google/gemini-cli
which gemini
"code2prompt command not found"
Install code2prompt:
cargo install code2prompt
# or
brew install mufeedvh/tap/code2prompt
Authentication Issues
Re-authenticate with Gemini CLI:
gemini
# Follow OAuth prompts again
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/***.logdist/**,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
Security Considerations
- Uses your existing Gemini CLI OAuth authentication
- No API keys stored in the MCP server
- Codebase content is sent to Gemini for analysis
- Consider data sensitivity when analyzing proprietary code
License
MIT License - See LICENSE file for details