feat: complete redesign to v2.4.0 - Claude's ultimate development partner
Major redesign of Gemini MCP Server with modular architecture: - Removed all emoji characters from tool outputs for clean terminal display - Kept review category emojis (🔴🟠🟡🟢) per user preference - Added 4 specialized tools: - think_deeper: Extended reasoning and problem-solving (temp 0.7) - review_code: Professional code review with severity levels (temp 0.2) - debug_issue: Root cause analysis and debugging (temp 0.2) - analyze: General-purpose file analysis (temp 0.2) - Modular architecture with base tool class and Pydantic models - Verbose tool descriptions with natural language triggers - Updated README with comprehensive examples and real-world use cases - All 25 tests passing, type checking clean, critical linting clean BREAKING CHANGE: Removed analyze_code tool in favor of specialized tools 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
705
README.md
705
README.md
@@ -1,58 +1,36 @@
|
||||
# Gemini MCP Server for Claude Code
|
||||
# Gemini MCP Server
|
||||
|
||||
A specialized Model Context Protocol (MCP) server that extends Claude Code's capabilities with Google's Gemini 2.5 Pro Preview, featuring a massive 1M token context window for handling large codebases and complex analysis tasks.
|
||||
The ultimate development partner for Claude - a Model Context Protocol server that gives Claude access to Google's Gemini 2.5 Pro for extended thinking, code analysis, and problem-solving.
|
||||
|
||||
## Purpose
|
||||
## Why This Server?
|
||||
|
||||
This server acts as a developer assistant that augments Claude Code when you need:
|
||||
- Analysis of files too large for Claude's context window
|
||||
- Deep architectural reviews across multiple files
|
||||
- Extended thinking and complex problem solving
|
||||
- Performance analysis of large codebases
|
||||
- Security audits requiring full codebase context
|
||||
Claude is brilliant, but sometimes you need:
|
||||
- **Extended thinking** on complex architectural decisions
|
||||
- **Deep code analysis** across massive codebases
|
||||
- **Expert debugging** for tricky issues
|
||||
- **Professional code reviews** with actionable feedback
|
||||
- **A senior developer partner** to validate and extend ideas
|
||||
|
||||
## Prerequisites
|
||||
This server makes Gemini your development sidekick, handling what Claude can't or extending what Claude starts.
|
||||
|
||||
Before you begin, ensure you have the following:
|
||||
## 🚀 Quickstart (5 minutes)
|
||||
|
||||
1. **Python:** Python 3.10 or newer. Check your version with `python3 --version`
|
||||
2. **Claude Desktop:** A working installation of Claude Desktop and the `claude` command-line tool
|
||||
3. **Gemini API Key:** An active API key from [Google AI Studio](https://aistudio.google.com/app/apikey)
|
||||
- Ensure your key is enabled for the `gemini-2.5-pro-preview` model
|
||||
4. **Git:** The `git` command-line tool for cloning the repository
|
||||
### 1. Get a Gemini API Key
|
||||
Visit [Google AI Studio](https://makersuite.google.com/app/apikey) and generate a free API key.
|
||||
|
||||
## Quick Start for Claude Code
|
||||
### 2. Install via Claude Desktop Config
|
||||
|
||||
### 1. Clone the Repository
|
||||
Add to your `claude_desktop_config.json`:
|
||||
|
||||
First, clone this repository to your local machine:
|
||||
```bash
|
||||
git clone https://github.com/BeehiveInnovations/gemini-mcp-server.git
|
||||
cd gemini-mcp-server
|
||||
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
||||
|
||||
# macOS/Linux only: Make the script executable
|
||||
chmod +x run_gemini.sh
|
||||
```
|
||||
|
||||
Note the full path to this directory - you'll need it for the configuration.
|
||||
|
||||
### 2. Configure in Claude Desktop
|
||||
|
||||
You can access the configuration file in two ways:
|
||||
- **Through Claude Desktop**: Open Claude Desktop → Settings → Developer → Edit Config
|
||||
- **Direct file access**:
|
||||
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
||||
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
|
||||
|
||||
Add the following configuration, replacing the path with your actual directory path:
|
||||
|
||||
**macOS**:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gemini": {
|
||||
"command": "/path/to/gemini-mcp-server/run_gemini.sh",
|
||||
"command": "python",
|
||||
"args": ["/absolute/path/to/gemini-mcp-server/server.py"],
|
||||
"env": {
|
||||
"GEMINI_API_KEY": "your-gemini-api-key-here"
|
||||
}
|
||||
@@ -61,156 +39,310 @@ Add the following configuration, replacing the path with your actual directory p
|
||||
}
|
||||
```
|
||||
|
||||
**Windows**:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gemini": {
|
||||
"command": "C:\\path\\to\\gemini-mcp-server\\run_gemini.bat",
|
||||
"env": {
|
||||
"GEMINI_API_KEY": "your-gemini-api-key-here"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Linux**:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gemini": {
|
||||
"command": "/path/to/gemini-mcp-server/run_gemini.sh",
|
||||
"env": {
|
||||
"GEMINI_API_KEY": "your-gemini-api-key-here"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Important**: Replace the path with the actual absolute path where you cloned the repository:
|
||||
- **macOS example**: `/Users/yourname/projects/gemini-mcp-server/run_gemini.sh`
|
||||
- **Windows example**: `C:\\Users\\yourname\\projects\\gemini-mcp-server\\run_gemini.bat`
|
||||
- **Linux example**: `/home/yourname/projects/gemini-mcp-server/run_gemini.sh`
|
||||
|
||||
### 3. Restart Claude Desktop
|
||||
|
||||
After adding the configuration, restart Claude Desktop. You'll see "gemini" in the MCP servers list.
|
||||
### 4. Start Using It!
|
||||
|
||||
### 4. Add to Claude Code
|
||||
Just ask Claude naturally:
|
||||
- "Think deeper about this architecture design"
|
||||
- "Review this code for security issues"
|
||||
- "Debug why this test is failing"
|
||||
- "Analyze these files to understand the data flow"
|
||||
|
||||
To make the server available in Claude Code, run:
|
||||
```bash
|
||||
# This command reads your Claude Desktop configuration and makes
|
||||
# the "gemini" server available in your terminal
|
||||
claude mcp add-from-claude-desktop -s user
|
||||
## 🧠 Available Tools
|
||||
|
||||
### `think_deeper` - Extended Reasoning Partner
|
||||
**When Claude needs to go deeper on complex problems**
|
||||
|
||||
#### Example Prompts:
|
||||
```
|
||||
|
||||
### 5. Start Using Natural Language
|
||||
|
||||
Just talk to Claude naturally:
|
||||
- "Use gemini analyze_file on main.py to find bugs"
|
||||
- "Share your analysis with gemini extended_think for deeper insights"
|
||||
- "Ask gemini to review the architecture using analyze_file"
|
||||
|
||||
**Key tools:**
|
||||
- `analyze_file` - Clean file analysis without terminal clutter
|
||||
- `extended_think` - Collaborative deep thinking with Claude's analysis
|
||||
- `chat` - General conversations
|
||||
- `analyze_code` - Legacy tool (prefer analyze_file for files)
|
||||
|
||||
## How It Works
|
||||
|
||||
This server acts as a local proxy between Claude Code and the Google Gemini API, following the Model Context Protocol (MCP):
|
||||
|
||||
1. You issue a command to Claude (e.g., "Ask Gemini to...")
|
||||
2. Claude Code sends a request to the local MCP server defined in your configuration
|
||||
3. This server receives the request, formats it for the Gemini API, and includes any file contents
|
||||
4. The request is sent to the Google Gemini API using your API key
|
||||
5. The server receives the response from Gemini
|
||||
6. The response is formatted and streamed back to Claude, who presents it to you
|
||||
|
||||
All processing and API communication happens locally from your machine. Your API key is never exposed to Anthropic.
|
||||
|
||||
## Developer-Optimized Features
|
||||
|
||||
### Automatic Developer Context
|
||||
When no custom system prompt is provided, Gemini automatically operates with deep developer expertise, focusing on:
|
||||
- Clean code principles
|
||||
- Performance optimization
|
||||
- Security best practices
|
||||
- Architectural patterns
|
||||
- Testing strategies
|
||||
- Modern development practices
|
||||
|
||||
### Optimized Temperature Settings
|
||||
- **General chat**: 0.5 (balanced accuracy with some creativity)
|
||||
- **Code analysis**: 0.2 (high precision for code review)
|
||||
|
||||
### Large Context Window
|
||||
- Handles up to 1M tokens (~4M characters)
|
||||
- Perfect for analyzing entire codebases
|
||||
- Maintains context across multiple large files
|
||||
|
||||
## Available Tools
|
||||
|
||||
### `chat`
|
||||
General-purpose developer conversations with Gemini.
|
||||
|
||||
**Example uses:**
|
||||
```
|
||||
"Ask Gemini about the best approach for implementing a distributed cache"
|
||||
"Use Gemini to explain the tradeoffs between different authentication strategies"
|
||||
```
|
||||
|
||||
### `analyze_code` (Legacy)
|
||||
Analyzes code files or snippets. For better terminal output, use `analyze_file` instead.
|
||||
|
||||
### `analyze_file` (Recommended for Files)
|
||||
Clean file analysis - always uses file paths, never shows content in terminal.
|
||||
|
||||
**Example uses:**
|
||||
```
|
||||
"Use gemini analyze_file on README.md to find issues"
|
||||
"Ask gemini to analyze_file main.py for performance problems"
|
||||
"Have gemini analyze_file on auth.py, users.py, and permissions.py together"
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Terminal always stays clean - only shows "Analyzing N file(s)"
|
||||
- Server reads files directly and sends to Gemini
|
||||
- No need to worry about prompt phrasing
|
||||
- Supports multiple files in one request
|
||||
|
||||
### `extended_think`
|
||||
Collaborate with Gemini on complex problems by sharing Claude's analysis for deeper insights.
|
||||
|
||||
**Example uses:**
|
||||
```
|
||||
"Share your analysis with gemini extended_think for deeper insights"
|
||||
"Use gemini extended_think to validate and extend your architectural design"
|
||||
"Ask gemini to extend your thinking on this security analysis"
|
||||
```
|
||||
|
||||
**Advanced usage with focus areas:**
|
||||
```
|
||||
"Use gemini extended_think with focus='performance' to drill into scaling issues"
|
||||
"Share your design with gemini extended_think focusing on security vulnerabilities"
|
||||
"Get gemini to extend your analysis with focus on edge cases"
|
||||
"Think deeper about my authentication design"
|
||||
"Ultrathink on this distributed system architecture"
|
||||
"Extend my analysis of this performance issue"
|
||||
"Challenge my assumptions about this approach"
|
||||
"Explore alternative solutions for this caching strategy"
|
||||
"Validate my microservices communication approach"
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Takes Claude's thoughts, plans, or analysis as input
|
||||
- Optional file context for reference
|
||||
- Configurable focus areas (architecture, bugs, performance, security)
|
||||
- Higher temperature (0.7) for creative problem-solving
|
||||
- Designed for collaborative thinking, not just code review
|
||||
- Extends Claude's analysis with alternative approaches
|
||||
- Finds edge cases and failure modes
|
||||
- Validates architectural decisions
|
||||
- Suggests concrete implementations
|
||||
- Temperature: 0.7 (creative problem-solving)
|
||||
|
||||
### `list_models`
|
||||
Lists available Gemini models (defaults to 2.5 Pro Preview).
|
||||
**Key Capabilities:**
|
||||
- Challenge assumptions constructively
|
||||
- Identify overlooked edge cases
|
||||
- Suggest alternative design patterns
|
||||
- Evaluate scalability implications
|
||||
- Consider security vulnerabilities
|
||||
- Assess technical debt impact
|
||||
|
||||
## Installation
|
||||
**Triggers:** think deeper, ultrathink, extend my analysis, explore alternatives, validate my approach
|
||||
|
||||
### `review_code` - Professional Code Review
|
||||
**Comprehensive code analysis with prioritized feedback**
|
||||
|
||||
#### Example Prompts:
|
||||
```
|
||||
"Review this code for issues"
|
||||
"Security audit of auth.py"
|
||||
"Quick review of my changes"
|
||||
"Check this code against PEP8 standards"
|
||||
"Review the authentication module focusing on OWASP top 10"
|
||||
"Performance review of the database queries in models.py"
|
||||
"Review api/ directory for REST API best practices"
|
||||
```
|
||||
|
||||
**Review Types:**
|
||||
- `full` - Complete review (default)
|
||||
- `security` - Security-focused analysis
|
||||
- `performance` - Performance optimization
|
||||
- `quick` - Critical issues only
|
||||
|
||||
**Output includes:**
|
||||
- Issues by severity with color coding:
|
||||
- 🔴 CRITICAL: Security vulnerabilities, data loss risks
|
||||
- 🟠 HIGH: Bugs, performance issues, bad practices
|
||||
- 🟡 MEDIUM: Code smells, maintainability issues
|
||||
- 🟢 LOW: Style issues, minor improvements
|
||||
- Specific fixes with code examples
|
||||
- Overall quality assessment
|
||||
- Top 3 priority improvements
|
||||
- Positive aspects worth preserving
|
||||
|
||||
**Customization Options:**
|
||||
- `focus_on`: Specific aspects to emphasize
|
||||
- `standards`: Coding standards to enforce (PEP8, ESLint, etc.)
|
||||
- `severity_filter`: Minimum severity to report
|
||||
|
||||
**Triggers:** review code, check for issues, find bugs, security check, code audit
|
||||
|
||||
### `debug_issue` - Expert Debugging Assistant
|
||||
**Root cause analysis for complex problems**
|
||||
|
||||
#### Example Prompts:
|
||||
```
|
||||
"Debug this TypeError in my async function"
|
||||
"Why is this test failing intermittently?"
|
||||
"Trace the root cause of this memory leak"
|
||||
"Debug this race condition"
|
||||
"Help me understand why the API returns 500 errors under load"
|
||||
"Debug why my WebSocket connections are dropping"
|
||||
"Find the root cause of this deadlock in my threading code"
|
||||
```
|
||||
|
||||
**Provides:**
|
||||
- Root cause identification
|
||||
- Step-by-step debugging approach
|
||||
- Immediate fixes
|
||||
- Long-term solutions
|
||||
- Prevention strategies
|
||||
|
||||
**Input Options:**
|
||||
- `error_description`: The error or symptom
|
||||
- `error_context`: Stack traces, logs, error messages
|
||||
- `relevant_files`: Files that might be involved
|
||||
- `runtime_info`: Environment, versions, configuration
|
||||
- `previous_attempts`: What you've already tried
|
||||
|
||||
**Triggers:** debug, error, failing, root cause, trace, not working, why is
|
||||
|
||||
### `analyze` - Smart File Analysis
|
||||
**General-purpose code understanding and exploration**
|
||||
|
||||
#### Example Prompts:
|
||||
```
|
||||
"Analyze main.py to understand the architecture"
|
||||
"Examine these files for circular dependencies"
|
||||
"Look for performance bottlenecks in this module"
|
||||
"Understand how these components interact"
|
||||
"Analyze the data flow through the pipeline modules"
|
||||
"Check if this module follows SOLID principles"
|
||||
"Analyze the API endpoints to create documentation"
|
||||
"Examine the test coverage and suggest missing tests"
|
||||
```
|
||||
|
||||
**Analysis Types:**
|
||||
- `architecture` - Design patterns, structure, dependencies
|
||||
- `performance` - Bottlenecks, optimization opportunities
|
||||
- `security` - Vulnerability assessment, security patterns
|
||||
- `quality` - Code metrics, maintainability, test coverage
|
||||
- `general` - Comprehensive analysis (default)
|
||||
|
||||
**Output Formats:**
|
||||
- `detailed` - Comprehensive analysis (default)
|
||||
- `summary` - High-level overview
|
||||
- `actionable` - Focused on specific improvements
|
||||
|
||||
**Special Features:**
|
||||
- Always uses file paths (not content) = clean terminal output!
|
||||
- Can analyze multiple files to understand relationships
|
||||
- Identifies patterns and anti-patterns
|
||||
- Suggests refactoring opportunities
|
||||
|
||||
**Triggers:** analyze, examine, look at, understand, inspect, check
|
||||
|
||||
### `chat` - General Development Chat
|
||||
**For everything else**
|
||||
|
||||
#### Example Prompts:
|
||||
```
|
||||
"Ask Gemini about the best caching strategy"
|
||||
"Explain how async generators work"
|
||||
"What's the difference between these design patterns?"
|
||||
"Compare Redis vs Memcached for my use case"
|
||||
"Explain the tradeoffs of microservices vs monolith"
|
||||
"Best practices for handling timezone data in Python"
|
||||
```
|
||||
|
||||
### Additional Utility Tools
|
||||
|
||||
#### `list_models` - See Available Gemini Models
|
||||
```
|
||||
"List available Gemini models"
|
||||
"Show me what models I can use"
|
||||
```
|
||||
|
||||
#### `get_version` - Server Information
|
||||
```
|
||||
"Get Gemini server version"
|
||||
"Show server configuration"
|
||||
```
|
||||
|
||||
## 📚 Real-World Examples
|
||||
|
||||
### Example 1: Comprehensive Security Review
|
||||
```
|
||||
You: "Review the auth/ directory for security issues, focus on JWT handling"
|
||||
Gemini:
|
||||
🔴 CRITICAL auth/jwt.py:45 - Secret key hardcoded
|
||||
→ Fix: Use environment variable
|
||||
SECRET_KEY = os.environ.get('JWT_SECRET')
|
||||
|
||||
🟠 HIGH auth/validate.py:23 - No token expiration check
|
||||
→ Fix: Add expiration validation
|
||||
if decoded['exp'] < time.time():
|
||||
raise TokenExpiredError()
|
||||
```
|
||||
|
||||
### Example 2: Performance Debugging
|
||||
```
|
||||
You: "Debug why the API endpoint /users/search is slow"
|
||||
Gemini:
|
||||
ROOT CAUSE: N+1 query problem in user search
|
||||
- Each user triggers separate query for roles
|
||||
- 100 users = 101 database queries
|
||||
|
||||
IMMEDIATE FIX:
|
||||
Add eager loading: User.query.options(joinedload('roles'))
|
||||
|
||||
LONG-TERM SOLUTION:
|
||||
Implement query result caching with Redis
|
||||
```
|
||||
|
||||
### Example 3: Architecture Analysis
|
||||
```
|
||||
You: "Analyze src/ to understand the architecture and identify improvements"
|
||||
Gemini:
|
||||
ARCHITECTURE OVERVIEW:
|
||||
- Layered architecture: Controllers → Services → Repositories
|
||||
- Good separation of concerns
|
||||
- Dependency injection pattern used
|
||||
|
||||
ISSUES FOUND:
|
||||
1. Circular dependency: UserService ↔ AuthService
|
||||
2. Missing abstraction for external APIs
|
||||
3. Business logic leaked into controllers
|
||||
|
||||
RECOMMENDATIONS:
|
||||
1. Extract shared logic to UserAuthService
|
||||
2. Add adapter pattern for external APIs
|
||||
3. Move validation to service layer
|
||||
```
|
||||
|
||||
## 💡 Power User Workflows
|
||||
|
||||
### 1. **Claude + Gemini Deep Thinking**
|
||||
```
|
||||
You: "Design a real-time collaborative editor"
|
||||
Claude: [provides initial design]
|
||||
You: "Think deeper about the conflict resolution"
|
||||
Gemini: [explores CRDTs, operational transforms, edge cases]
|
||||
You: "Update the design based on Gemini's insights"
|
||||
Claude: [refines with deeper understanding]
|
||||
```
|
||||
|
||||
### 2. **Comprehensive Code Review**
|
||||
```
|
||||
You: "Review api/auth.py focusing on security"
|
||||
Gemini: [identifies SQL injection risk, suggests prepared statements]
|
||||
You: "Fix the critical issues Gemini found"
|
||||
Claude: [implements secure solution]
|
||||
```
|
||||
|
||||
### 3. **Complex Debugging**
|
||||
```
|
||||
Claude: "I see the error but the root cause isn't clear..."
|
||||
You: "Debug this with the error context and relevant files"
|
||||
Gemini: [traces execution, identifies race condition]
|
||||
You: "Implement Gemini's suggested fix"
|
||||
```
|
||||
|
||||
### 4. **Architecture Validation**
|
||||
```
|
||||
You: "I've designed a microservices architecture [details]"
|
||||
You: "Think deeper about scalability and failure modes"
|
||||
Gemini: [analyzes bottlenecks, suggests circuit breakers, identifies edge cases]
|
||||
```
|
||||
|
||||
## 🎯 Pro Tips
|
||||
|
||||
### Natural Language Triggers
|
||||
The server recognizes natural phrases. Just talk normally:
|
||||
- ❌ "Use the think_deeper tool with current_analysis parameter..."
|
||||
- ✅ "Think deeper about this approach"
|
||||
|
||||
### Automatic Tool Selection
|
||||
Claude will automatically pick the right tool based on your request:
|
||||
- "review" → `review_code`
|
||||
- "debug" → `debug_issue`
|
||||
- "analyze" → `analyze`
|
||||
- "think deeper" → `think_deeper`
|
||||
|
||||
### Clean Terminal Output
|
||||
All file operations use paths, not content, so your terminal stays readable even with large files.
|
||||
|
||||
### Context Awareness
|
||||
Tools can reference files for additional context:
|
||||
```
|
||||
"Debug this error with context from app.py and config.py"
|
||||
"Think deeper about my design, reference the current architecture.md"
|
||||
```
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```
|
||||
gemini-mcp-server/
|
||||
├── server.py # Main server
|
||||
├── config.py # Configuration
|
||||
├── tools/ # Tool implementations
|
||||
│ ├── think_deeper.py
|
||||
│ ├── review_code.py
|
||||
│ ├── debug_issue.py
|
||||
│ └── analyze.py
|
||||
├── prompts/ # System prompts
|
||||
└── utils/ # Utilities
|
||||
```
|
||||
|
||||
**Extensible Design:**
|
||||
- Each tool is a self-contained module
|
||||
- Easy to add new tools
|
||||
- Consistent interface
|
||||
- Type-safe with Pydantic
|
||||
|
||||
## 🔧 Installation
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
@@ -234,210 +366,21 @@ Lists available Gemini models (defaults to 2.5 Pro Preview).
|
||||
export GEMINI_API_KEY="your-api-key-here"
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
## 🤝 Contributing
|
||||
|
||||
### Custom System Prompts
|
||||
Override the default developer prompt when needed:
|
||||
```python
|
||||
{
|
||||
"prompt": "Review this code",
|
||||
"system_prompt": "You are a security expert. Focus only on vulnerabilities."
|
||||
}
|
||||
```
|
||||
We welcome contributions! The modular architecture makes it easy to add new tools:
|
||||
|
||||
### Temperature Control
|
||||
Adjust for your use case:
|
||||
- `0.1-0.3`: Maximum precision (debugging, security analysis)
|
||||
- `0.4-0.6`: Balanced (general development tasks)
|
||||
- `0.7-0.9`: Creative solutions (architecture design, brainstorming)
|
||||
1. Create a new tool in `tools/`
|
||||
2. Inherit from `BaseTool`
|
||||
3. Implement required methods
|
||||
4. Add to `TOOLS` in `server.py`
|
||||
|
||||
### Model Selection
|
||||
While defaulting to `gemini-2.5-pro-preview-06-05`, you can specify other models:
|
||||
- `gemini-1.5-pro-latest`: Stable alternative
|
||||
- `gemini-1.5-flash`: Faster responses
|
||||
- Use `list_models` to see all available options
|
||||
See existing tools for examples.
|
||||
|
||||
## Claude Code Integration Examples
|
||||
## 📝 License
|
||||
|
||||
### When Claude hits token limits:
|
||||
```
|
||||
Claude: "This file is too large for me to analyze fully..."
|
||||
You: "Use Gemini to analyze the entire file and identify the main components"
|
||||
```
|
||||
MIT License - see LICENSE file for details.
|
||||
|
||||
### For architecture reviews:
|
||||
```
|
||||
You: "Use Gemini to analyze all files in /src/core/ and create an architecture diagram"
|
||||
```
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
### For performance optimization:
|
||||
```
|
||||
You: "Have Gemini profile this codebase and suggest the top 5 performance improvements"
|
||||
```
|
||||
|
||||
## Practical Usage Tips
|
||||
|
||||
### Effective Commands
|
||||
Be specific about what you want from Gemini:
|
||||
- Good: "Ask Gemini to identify memory leaks in this code"
|
||||
- Bad: "Ask Gemini about this"
|
||||
|
||||
### Clean Terminal Output
|
||||
When analyzing files, explicitly mention the files parameter:
|
||||
- "Use gemini analyze_code with files=['app.py'] to find bugs"
|
||||
- "Analyze package.json using gemini's files parameter"
|
||||
This prevents Claude from displaying the entire file content in your terminal.
|
||||
|
||||
### Common Workflows
|
||||
|
||||
#### 1. **Extended Thinking Partnership**
|
||||
```
|
||||
You: "Design a distributed task queue system"
|
||||
Claude: [provides detailed architecture and implementation plan]
|
||||
You: "Use gemini extended_think to validate and extend this design"
|
||||
Gemini: [identifies gaps, suggests alternatives, finds edge cases]
|
||||
You: "Address the issues Gemini found"
|
||||
Claude: [updates design with improvements]
|
||||
```
|
||||
|
||||
#### 2. **Clean File Analysis (No Terminal Clutter)**
|
||||
```
|
||||
"Use gemini analyze_file on engine.py to find performance issues"
|
||||
"Ask gemini to analyze_file database.py and suggest optimizations"
|
||||
"Have gemini analyze_file on all files in /src/core/"
|
||||
```
|
||||
|
||||
#### 3. **Multi-File Architecture Review**
|
||||
```
|
||||
"Use gemini analyze_file on auth.py, users.py, permissions.py to map dependencies"
|
||||
"Ask gemini to analyze_file the entire /src/api/ directory for security issues"
|
||||
"Have gemini analyze_file all model files to check for N+1 queries"
|
||||
```
|
||||
|
||||
#### 4. **Deep Collaborative Analysis**
|
||||
```
|
||||
Claude: "Here's my analysis of the memory leak: [detailed investigation]"
|
||||
You: "Share this with gemini extended_think focusing on root causes"
|
||||
|
||||
Claude: "I've designed this caching strategy: [detailed design]"
|
||||
You: "Use gemini extended_think with focus='performance' to stress-test this design"
|
||||
|
||||
Claude: "Here's my security assessment: [findings]"
|
||||
You: "Get gemini to extended_think on this with files=['auth.py', 'crypto.py'] for context"
|
||||
```
|
||||
|
||||
#### 4. **Claude-Driven Design with Gemini Validation**
|
||||
```
|
||||
Claude: "I've designed a caching strategy using Redis with TTL-based expiration..."
|
||||
You: "Share my caching design with Gemini and ask for edge cases I might have missed"
|
||||
|
||||
Claude: "Here's my implementation plan for the authentication system: [detailed plan]"
|
||||
You: "Use Gemini to analyze this plan and identify security vulnerabilities or scalability issues"
|
||||
|
||||
Claude: "I'm thinking of using this approach for the data pipeline: [approach details]"
|
||||
You: "Have Gemini review my approach and check these 10 files for compatibility issues"
|
||||
```
|
||||
|
||||
#### 5. **Security & Performance Audits**
|
||||
```
|
||||
"Use Gemini to security audit this authentication flow"
|
||||
"Have Gemini identify performance bottlenecks in this codebase"
|
||||
"Ask Gemini to check for common security vulnerabilities"
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
- Let Claude do the primary thinking and design work
|
||||
- Use Gemini as a validation layer for edge cases and extended context
|
||||
- Share Claude's complete thoughts with Gemini for comprehensive review
|
||||
- Have Gemini analyze files that are too large for Claude
|
||||
- Use the feedback loop: Claude designs → Gemini validates → Claude refines
|
||||
|
||||
### Real-World Example Flow
|
||||
```
|
||||
1. You: "Create a microservices architecture for our e-commerce platform"
|
||||
2. Claude: [Designs comprehensive architecture with service boundaries, APIs, data flow]
|
||||
3. You: "Take my complete architecture design and have Gemini analyze it for:
|
||||
- Potential bottlenecks
|
||||
- Missing error handling
|
||||
- Security vulnerabilities
|
||||
- Scalability concerns"
|
||||
4. Gemini: [Provides detailed analysis with specific concerns]
|
||||
5. You: "Based on Gemini's analysis, update the architecture"
|
||||
6. Claude: [Refines design addressing all concerns]
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Gemini 2.5 Pro Preview may occasionally block certain prompts due to safety filters
|
||||
- If a prompt is blocked by Google's safety filters, the server will return a clear error message to Claude explaining why the request could not be completed
|
||||
- Token estimation: ~4 characters per token
|
||||
- All file paths should be absolute paths
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Server Not Appearing in Claude
|
||||
|
||||
- **Check JSON validity:** Ensure your `claude_desktop_config.json` file is valid JSON (no trailing commas, proper quotes)
|
||||
- **Verify absolute paths:** The `command` path must be an absolute path to `run_gemini.sh` or `run_gemini.bat`
|
||||
- **Restart Claude Desktop:** Always restart Claude Desktop completely after any configuration change
|
||||
|
||||
### Gemini Commands Fail
|
||||
|
||||
- **"API Key not valid" errors:** Verify your `GEMINI_API_KEY` is correct and active in [Google AI Studio](https://aistudio.google.com/app/apikey)
|
||||
- **"Permission denied" errors:**
|
||||
- Ensure your API key is enabled for the `gemini-2.5-pro-preview` model
|
||||
- On macOS/Linux, check that `run_gemini.sh` has execute permissions (`chmod +x run_gemini.sh`)
|
||||
- **Network errors:** If behind a corporate firewall, ensure requests to `https://generativelanguage.googleapis.com` are allowed
|
||||
|
||||
### Common Setup Issues
|
||||
|
||||
- **"Module not found" errors:** The virtual environment may not be activated. See the Installation section
|
||||
- **`chmod: command not found` (Windows):** The `chmod +x` command is for macOS/Linux only. Windows users can skip this step
|
||||
- **Path not found errors:** Use absolute paths in all configurations, not relative paths like `./run_gemini.sh`
|
||||
|
||||
## Testing
|
||||
|
||||
### Running Tests Locally
|
||||
|
||||
```bash
|
||||
# Install development dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Run tests with coverage
|
||||
pytest
|
||||
|
||||
# Run tests with verbose output
|
||||
pytest -v
|
||||
|
||||
# Run specific test file
|
||||
pytest tests/test_gemini_server.py
|
||||
|
||||
# Generate HTML coverage report
|
||||
pytest --cov-report=html
|
||||
open htmlcov/index.html # View coverage report
|
||||
```
|
||||
|
||||
### Continuous Integration
|
||||
|
||||
This project uses GitHub Actions for automated testing:
|
||||
- Tests run on every push and pull request
|
||||
- Supports Python 3.8 - 3.12
|
||||
- Tests on Ubuntu, macOS, and Windows
|
||||
- Includes linting with flake8, black, isort, and mypy
|
||||
- Maintains 80%+ code coverage
|
||||
|
||||
## Contributing
|
||||
|
||||
This server is designed specifically for Claude Code users. Contributions that enhance the developer experience are welcome!
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Write tests for your changes
|
||||
4. Ensure all tests pass (`pytest`)
|
||||
5. Commit your changes (`git commit -m 'Add amazing feature'`)
|
||||
6. Push to the branch (`git push origin feature/amazing-feature`)
|
||||
7. Open a Pull Request
|
||||
|
||||
## License
|
||||
|
||||
MIT License - feel free to customize for your development workflow.
|
||||
Built with [MCP](https://modelcontextprotocol.com) by Anthropic and powered by Google's Gemini API.
|
||||
Reference in New Issue
Block a user