README.md•9.41 kB
# Gemini MCP Server
An MCP (Model Context Protocol) server that provides tools for analyzing codebases using the Gemini CLI. This server leverages Gemini's massive context window to perform comprehensive codebase analysis, verification, and security audits.
## Features
- **File Analysis**: Analyze specific files using Gemini's @ syntax
- **Directory Analysis**: Analyze entire directories and subdirectories
- **All Files Analysis**: Analyze complete projects using --all_files flag
- **Implementation Verification**: Check if specific features are implemented
- **Security Audits**: Perform security analysis for common vulnerabilities
- **Architecture Analysis**: Analyze codebase structure and patterns
## Prerequisites
1. **Gemini CLI**: You must have the Gemini CLI installed and configured
```bash
# Using npx (no installation required)
npx https://github.com/google-gemini/gemini-cli
# Install Gemini CLI (example - check official docs for latest instructions)
npm install -g @google/gemini-cli@latest
# or
brew install gemini-cli
```
2. **Python 3.12+** and **uv** package manager
## Installation
1. Clone or download this project
2. Install dependencies:
```bash
cd gemini-mcp
uv sync
```
## Usage
### Running the MCP Server
```bash
# Run directly
uv run python -m gemini_mcp
# Or install and run
uv pip install -e .
gemini-mcp
```
### Available Tools
#### 1. `gemini_analyze_files`
Analyze specific files using Gemini CLI with @ syntax.
**Parameters:**
- `files` (array): List of file paths to analyze
- `prompt` (string): Analysis prompt to send to Gemini
- `working_directory` (optional): Directory to run command from
**Example:**
```json
{
"name": "gemini_analyze_files",
"arguments": {
"files": ["src/main.py", "src/utils.py"],
"prompt": "Explain the purpose and structure of these files"
}
}
```
#### 2. `gemini_analyze_directories`
Analyze entire directories using Gemini CLI.
**Parameters:**
- `directories` (array): List of directory paths to analyze
- `prompt` (string): Analysis prompt to send to Gemini
- `working_directory` (optional): Directory to run command from
**Example:**
```json
{
"name": "gemini_analyze_directories",
"arguments": {
"directories": ["src", "tests"],
"prompt": "Analyze test coverage for the source code"
}
}
```
#### 3. `gemini_analyze_all_files`
Analyze all files in the current directory using --all_files flag.
**Parameters:**
- `prompt` (string): Analysis prompt to send to Gemini
- `working_directory` (optional): Directory to run command from
**Example:**
```json
{
"name": "gemini_analyze_all_files",
"arguments": {
"prompt": "Give me an overview of this entire project"
}
}
```
#### 4. `gemini_verify_implementation`
Verify if specific features or patterns are implemented in the codebase.
**Parameters:**
- `feature_name` (string): Name of the feature to verify
- `search_paths` (array): Directories/files to search in
- `verification_prompt` (optional): Custom verification prompt
- `working_directory` (optional): Directory to run command from
**Example:**
```json
{
"name": "gemini_verify_implementation",
"arguments": {
"feature_name": "JWT authentication",
"search_paths": ["src", "middleware"]
}
}
```
#### 5. `gemini_security_audit`
Perform security analysis of the codebase.
**Parameters:**
- `audit_type` (enum): Type of audit - `sql_injection`, `xss`, `auth`, `general`, `input_validation`
- `paths` (array): Paths to audit (files or directories)
- `working_directory` (optional): Directory to run command from
**Example:**
```json
{
"name": "gemini_security_audit",
"arguments": {
"audit_type": "sql_injection",
"paths": ["src/api", "src/database"]
}
}
```
#### 6. `gemini_architecture_analysis`
Analyze codebase architecture and patterns.
**Parameters:**
- `analysis_type` (enum): Type of analysis - `overview`, `dependencies`, `patterns`, `structure`, `coupling`
- `paths` (array): Paths to analyze
- `working_directory` (optional): Directory to run command from
**Example:**
```json
{
"name": "gemini_architecture_analysis",
"arguments": {
"analysis_type": "overview",
"paths": ["src"]
}
}
```
## Integration with Claude Code
### Using claude mcp command (Recommended)
The easiest way to add this MCP server to Claude Code is using the built-in `claude mcp` command with uv's script dependencies:
```bash
# Add the MCP server using uv script execution
claude mcp add gemini-mcp uv run /path/to/gemini-mcp/src/gemini_mcp/__init__.py
```
Or if you want to install it globally first:
```bash
cd /path/to/gemini-mcp
uv pip install -e .
claude mcp add gemini-mcp gemini-mcp
```
### Manual Configuration
Alternatively, you can manually add it to your MCP configuration:
```json
{
"mcpServers": {
"gemini-mcp": {
"command": "uv",
"args": ["run", "python", "-m", "gemini_mcp"],
"cwd": "/path/to/gemini-mcp"
}
}
}
```
Or if installed globally:
```json
{
"mcpServers": {
"gemini-mcp": {
"command": "gemini-mcp"
}
}
}
```
### Managing the MCP Server
```bash
# List all MCP servers
claude mcp list
# Remove the server if needed
claude mcp remove gemini-mcp
# Re-add after updates
claude mcp add gemini-mcp uv run /path/to/gemini-mcp/src/gemini_mcp/__init__.py
```
### Using MCP Prompts
The server exposes prompts that can be used directly via slash commands:
```bash
# Analyze specific files
/mcp__gemini_mcp__analyze_files files=src/main.py,src/utils.py
# Security audit
/mcp__gemini_mcp__security_audit audit_type=sql_injection paths=src/api,src/database
# Architecture analysis
/mcp__gemini_mcp__architecture_analysis analysis_type=overview paths=src
# Verify if a feature is implemented
/mcp__gemini_mcp__verify_feature feature_name="JWT authentication" search_paths=src,middleware
# Get project overview
/mcp__gemini_mcp__project_overview
# Get focused project overview
/mcp__gemini_mcp__project_overview focus="API architecture"
```
### Available Prompts
The MCP server exposes the following prompts:
1. **`analyze_files`** - Analyze specific files with optional custom prompt
- Arguments: `files` (required), `prompt` (optional)
2. **`security_audit`** - Perform security audits
- Arguments: `audit_type` (required: sql_injection, xss, auth, general, input_validation), `paths` (required)
3. **`architecture_analysis`** - Analyze codebase architecture
- Arguments: `analysis_type` (required: overview, dependencies, patterns, structure, coupling), `paths` (required)
4. **`verify_feature`** - Verify if features are implemented
- Arguments: `feature_name` (required), `search_paths` (optional)
5. **`project_overview`** - Get comprehensive project overview
- Arguments: `focus` (optional)
## Use Cases
### Large Codebase Analysis
When analyzing large codebases that exceed Claude's context limits, use Gemini's massive context window:
- Full project overviews
- Cross-file dependency analysis
- Architecture documentation generation
### Feature Verification
Check if specific features are implemented:
- Authentication systems
- Error handling patterns
- Security measures
- Design patterns
### Security Audits
Perform comprehensive security analysis:
- SQL injection vulnerability scanning
- XSS vulnerability detection
- Authentication/authorization review
- Input validation analysis
### Code Quality Assessment
Analyze code quality and structure:
- Architectural pattern compliance
- Code organization evaluation
- Coupling analysis
- Dependency management review
## Development
### Project Structure
```
gemini-mcp/
src/
gemini_mcp/
__init__.py # Main MCP server implementation
pyproject.toml # Project configuration
README.md # This file
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
This project is licensed under the MIT License.
## Troubleshooting
### Common Issues
1. **"Gemini CLI not found"**
- Ensure Gemini CLI is installed and in your PATH
- Verify installation with `which gemini`
2. **API Key Issues**
- Configure Gemini CLI with your API key: `gemini config set api-key YOUR_KEY`
- Check if the key is valid with a simple test: `gemini -p "Hello"`
3. **Permission Errors**
- Ensure the working directory is accessible
- Check file permissions for the files you're trying to analyze
4. **Large File Timeouts**
- For very large codebases, consider analyzing specific subdirectories first
- Use the directory analysis tools to break down the analysis
### Updates and Maintenance
For updates to this local MCP server:
```bash
# If this is a git repository
cd /path/to/gemini-mcp
git pull
uv sync
# Update dependencies
uv sync --upgrade
# If installed with -e flag, changes are automatically reflected
# Otherwise, reinstall after updates:
uv pip install -e .
```
Since this is installed in "editable" mode with `-e`, code changes are automatically reflected without reinstalling.
### Support
For issues specific to this MCP server, please check the logs and ensure:
- Gemini CLI is properly installed and configured
- File paths are correct and accessible
- Working directory permissions are set correctly
For Gemini CLI issues, refer to the official Gemini documentation.