README.md•5.72 kB
# 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
1. **Node.js 18+** - For running the MCP server
2. **Gemini CLI** - Google's CLI tool with OAuth authentication
3. **code2prompt** - Rust CLI tool for codebase extraction
4. **Claude Code** - For sub-agent integration
### Installation Steps
#### 1. Install Gemini CLI
```bash
npm install -g @google/gemini-cli
```
Authenticate with your Google account:
```bash
gemini
# Follow OAuth setup prompts
```
#### 2. Install code2prompt
```bash
# macOS/Linux with Homebrew
brew install mufeedvh/tap/code2prompt
# Or build from source
cargo install code2prompt
```
#### 3. Install MCP Server Dependencies
```bash
cd /Users/ryangould/Dev/gemini-cli-mcp
npm install
```
## Setup & Configuration
### 1. Build the MCP Server
```bash
npm run build
```
### 2. Configure Claude Code MCP Settings
Add to your Claude Code MCP settings (usually `~/.config/claude-desktop/mcp_settings.json`):
```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 directory
- `excludePatterns` (array, optional): Additional patterns to exclude
**Usage Example:**
```typescript
// 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:**
```typescript
// 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:
1. Use `/tools` to see available MCP tools
2. Select `gemini_comprehensive_review` or `gemini_targeted_analysis`
3. Provide required parameters
## Development
### Running in Development Mode
```bash
npm run dev
```
### Building for Production
```bash
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:
```bash
npm install -g @google/gemini-cli
which gemini
```
#### "code2prompt command not found"
Install code2prompt:
```bash
cargo install code2prompt
# or
brew install mufeedvh/tap/code2prompt
```
#### Authentication Issues
Re-authenticate with Gemini CLI:
```bash
gemini
# Follow OAuth prompts again
```
#### MCP Server Not Connecting
1. Check Claude Code MCP settings configuration
2. Verify the server path is correct
3. Check console logs for errors
4. Restart Claude Code after configuration changes
### Logging
The MCP server logs to stderr. Monitor logs when running:
```bash
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
## 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