Gemini CLI MCP Server

A production-ready Model Context Protocol (MCP) server that bridges Google's Gemini CLI with MCP-compatible clients like Claude Code and Claude Desktop. This enterprise-grade Gemini MCP server features OpenRouter AI API integration for access to 400+ AI models and provides 33 specialized tools for seamless multi-AI workflows between Claude, Gemini, and 400+ additional models.

On Claude Desktop:

Example 1: Claude Code calling one of the 33 MCP tools, gemini_prompt:

Example 2: Claude Code Custom Slash Command Prompt + Claude & Gemini CLI MCP Server Teamwork

Setup Claude Code custom slash command prompt /test-gemini-prompt-analyse-teamwork within Git repo project at .claude/commands/test-mcp/test-gemini-prompt-analyse-teamwork.md. When you invoke this command, Claude Code Sonnet 4 first performs a deep analysis of the Gemini CLI MCP server code. It then delegates the same codebase to Google Gemini 2.5 Flash via the MCP tool’s @gemini_prompt() (note that Flash may be rate-limited on free tiers). Finally, Claude Code Sonnet 4 synthesizes both sets of insights into a single, consolidated report.

Click View Screenshots to see example.

Example 3: Claude Code Custom Slash Command Prompt + Claude & Gemini CLI MCP Server Comphrensive Review

Setup Claude Code custom slash command prompt .claude/commands/workflow-orchestrators/comprehensive-review.md within Git repo project at .claude/commands/workflow-orchestrators/comprehensive-review.md. When you invoke this command, Claude Code Sonnet 4 first performs a comphrensive review of the Gemini CLI MCP server code and writes a report. It then asks Google Gemini 2.5 Flash via the MCP tool’s @gemini_prompt() (note that Flash may be rate-limited on free tiers) to verify and evaluate the generated report and add it's findings to the report.

Click View Screenshots to see example.

Example 4: Extended: Claude Code Custom Slash Command Prompt + Claude & Gemini CLI MCP Server Comphrensive Review + Claude Response To Gemini Analysis.

Setup Claude Code custom slash command prompt .claude/commands/workflow-orchestrators/comprehensive-review.md within Git repo project at .claude/commands/workflow-orchestrators/comprehensive-review.md. When you invoke this command, Claude Code Sonnet 4 first performs a comphrensive review of the Gemini CLI MCP server code and writes a report. It then asks Google Gemini 2.5 Flash via the MCP tool’s @gemini_prompt() (note that Flash may be rate-limited on free tiers) to verify and evaluate the generated report and add it's findings to the report. Then finally ask Claude to respond to Gemini CLI MCP server's analysis.

Click View Screenshots to see example.

Example 5: Claude Code with Gemini CLI MCP Server With OpenRouter API support

Extended Gemini CLI MCP server with Openrouter API support to access 400+ LLM models. Click View Screenshots to see example of Claude Code chatting with Openai GP4 4.1-nano, Mistral AI devstral-small and DeepSeek R1 0528.

Example 6: Claude Code with Gemini CLI MCP Server AI Collaboration

The Gemini CLI MCP server includes OpenRouter API support for accessing 400+ LLM models. The @gemini_ai_collaboration MCP tool enables multiple AI models to engage in structured conversations, collaborations, or debates. This allows Gemini 2.5 models (via Gemini CLI) to collaborate with OpenRouter-based models like OpenAI GPT-4, Anthropic Claude, and others.

In the example below, Gemini 2.5 Flash debates with OpenAI GPT-4.1-mini through Claude Code. Claude Code (Sonnet 4) orchestrates the debate and has full access to the conversation context, enabling sophisticated multi-AI workflows.

Using Gemini CLI MCP in Claude Desktop with same MCP tool:

Or validation mode with Gemini 2.5 Flash, OpenAI GPT-4.1-mini and Anthropic Claude 3 Haiku.

Example 7: Claude Code natural language prompt calling Gemini CLI MCP server's Openrouter LLM model, OpenAI GPT 4.1-nano.

Claude Code natural language prompt calling Gemini CLI MCP server's Openrouter LLM model, OpenAI GPT 4.1-nano.

Click View Screenshots to see example.

Seems there is a bug in that it says it gets 4o-mini but I wanted/do get 4.1-nano model as asked.

OpenRouter Usage Activity for OpenAI GPT 4.1-nano

Gemini CLI MCP server uses Cloudflare AI Gateway proxies for Gemini CLI itself and also for OpenRouter integration. But AI Gateway records it as 4.1-mini and not 4.1-nano.

🚀 Key Features

• 33 Specialized MCP Tools - Complete toolset for multi-AI integration across 6 tool categories

• 400+ AI Models - Access to OpenAI, Anthropic, Meta, Google, and 20+ providers via OpenRouter integration

• Enterprise Architecture - Refactored modular design with 83 Python files organized across multiple specialized modules

• Conversation History - Stateful multi-turn conversations with Redis-backed storage and cross-platform support

• Dynamic Token Limits - Tool-specific limits from 100K-800K characters with model-aware scaling

• Multi-AI Workflows - Purpose-built tools for plan evaluation, code review, and cross-platform collaboration

• @filename Support - Direct file reading with intelligent large file handling strategies for 32 tools

• Enterprise Security - 22 critical security fixes with multi-layer defense and real-time protection

• Production Ready - 2,500+ test cases, enterprise monitoring with OpenTelemetry + Prometheus

• High Concurrency - Async architecture supporting 1,000-10,000+ concurrent requests with 10-100x improvement

📋 Table of Contents

• Architecture Overview

• Tool Suite

  • Core Gemini Tools

  • System Tools

  • Analysis Tools

  • Conversation Tools

  • Specialized Code Review Tools

  • Content Comparison Tools

  • AI Collaboration Tools

  • OpenRouter Tools

• Installation

• MCP Client Configuration

• Usage Examples

• Advanced Features

• Configuration

• Performance

• Testing

• Troubleshooting

🏗️ Architecture Overview

The Gemini CLI MCP Server features a modular, enterprise-grade architecture designed for reliability, performance, and maintainability. Built on proven architectural patterns and production-ready design decisions.

Core Components

🔧 Refactored Modular Architecture (83 Python files across multiple specialized modules):

Core Server Layer (6 modules):

• mcp_server.py - Streamlined main coordinator with tool registration pattern (741 lines, 83.5% reduction from 4,502 lines)

• modules/core/mcp_core_tools.py - Pure MCP tool implementations for core Gemini CLI tools (487 lines)

• modules/core/mcp_collaboration_engine.py - AI collaboration system with advanced workflow modes (1,103 lines)

• modules/core/mcp_service_implementations.py - System and service tools coordination layer (1,228 lines)

• modules/core/mcp_code_review_tools.py - Specialized code review and analysis tools (386 lines)

• modules/core/mcp_content_comparison_tools.py - Multi-source content comparison capabilities (299 lines)

Configuration & Infrastructure (7 modules):

• modules/config/gemini_config.py - Main configuration interface with modular imports (1,835 lines)

• modules/config/environment_config.py - Environment variable parsing and validation (NEW)

• modules/config/model_config.py - Gemini model definitions and scaling configuration (NEW)

• modules/config/feature_config.py - Feature flags, OpenRouter, monitoring, and conversations (NEW)

• modules/utils/gemini_utils.py - Core utilities and helper functions (3,996 lines)

• modules/services/conversation_manager.py - Stateful conversation management with Redis support (1,048 lines)

• modules/services/monitoring.py - OpenTelemetry, Prometheus, and health check integration (1,534 lines)

Integration Modules (2 modules):

• modules/services/openrouter_client.py - OpenRouter API client for 400+ AI models (881 lines)

• modules/services/redis_cache.py - Redis caching with graceful memory fallback (914 lines)

Template System (17 modules):

• prompts/ - Template module with TTL caching and integrity verification

• Core templates: template_loader.py, base_template.py, eval_template.py, review_template.py, verify_template.py, summarize_template.py

• Collaboration templates: debate_template.py, sequential_template.py, validation_template.py

• Code review templates: code_review_template.py, extract_structured_template.py, git_diff_review_template.py (NEW)

• Content analysis templates: content_comparison_template.py (NEW)

• Plus interface and supporting files

Security Framework (6 modules):

• security/ - Enterprise security framework with 22 critical security fixes

• Includes: api_key_manager.py, credential_sanitizer.py, pattern_detector.py, security_monitor.py, security_validator.py, jsonrpc_validator.py

Rate Limiting & Utility Scripts (5 modules):

• Rate Limiting Framework (3 modules): per_model_rate_limiter.py, rate_limit_config.py, rate_limit_integration.py

• Utility Scripts (2 modules): rotate_openrouter_key.py, security_audit.py

📝 Template System Architecture:

Key Template Features:

• Template Extraction: Large prompt templates separated from function logic for maintainability

• TTL Caching: 30-minute cache for template loading with performance optimization

• Modular Design: Each dual-AI workflow tool has dedicated template files

• Function Size Reduction: ~70% average reduction in function complexity

• Performance: Cached templates improve response times for repeated operations

⚡ Enterprise Features:

• 10-100x Concurrency Improvement: Lock-free cache operations with atomic get-or-set patterns

• Advanced Caching System: TTL-based caching with template integrity verification using SHA-256 hashing

• Process Pooling: Configurable ProcessPoolExecutor reducing 100-500ms subprocess creation overhead

• Automatic Model Fallback: gemini-2.5-pro → gemini-2.5-flash with intelligent quota management

• Enterprise Monitoring: OpenTelemetry tracing + Prometheus metrics with graceful degradation

• 90% Rate Limiting Optimization: Deque-based O(1) algorithms with memory leak protection

🛡️ Security & Reliability:

• 22 Critical Security Fixes: Session-based rate limiting, template integrity validation, enhanced credential sanitization, JSON-RPC validation, subprocess injection protection

• Multi-layer Defense: 25+ attack categories with compiled regex patterns for real-time protection

• Security Pattern Detection: Protection against command injection, path traversal, XSS, prompt injection, information disclosure

• Memory-Safe Operations: Bounded caches with automatic cleanup and O(1) operations

• JSON-RPC Security Middleware: Protocol-level validation with request size limits and nesting depth protection

• Structured Error Handling: Comprehensive error taxonomy with sanitized client responses

• Enterprise Compliance: OWASP Top 10 aligned with NIST security guidelines

Key Architectural Decisions

🏛️ Design Philosophy:

• FastMCP Framework: Official MCP Python SDK with JSON-RPC 2.0 compliance

• Dual Input Support: Both string and list command inputs for security and compatibility

• Direct Subprocess Execution: Avoids shell injection vulnerabilities

• Structured Error Classification: 11 error codes with machine-readable responses

• Multi-Tier TTL Caching: Different cache durations optimized for each use case

• Full Async/Await: High-concurrency architecture supporting 1,000-10,000+ requests

• Configurable Fallback: Environment-driven behavior for empty command handling

• Exponential Backoff Retry: Intelligent retry logic with jitter for transient errors

• Input Validation: Multi-layer validation with length limits and sanitization

• Information Disclosure Prevention: Sanitized client responses with detailed server logging

🛠️ Tool Suite

The server provides 33 specialized MCP tools organized into six categories:

Core Gemini Tools (6)

gemini_cli

Execute any Gemini CLI command directly with comprehensive error handling.

gemini_help

Get cached Gemini CLI help information (30-minute TTL).

gemini_version

Get cached Gemini CLI version information (30-minute TTL).

gemini_prompt

Send prompts with structured parameters and validation (100,000 char limit).

gemini_models

List all available Gemini AI models.

gemini_metrics

Get comprehensive server performance metrics and statistics.

System Tools (3)

gemini_sandbox

Execute prompts in sandbox mode for code execution (200,000 char limit).

gemini_cache_stats

Get cache statistics for all cache backends.

gemini_rate_limiting_stats

Get comprehensive rate limiting and quota statistics.

Analysis Tools (5)

gemini_summarize

Summarize content with focus-specific analysis (400,000 char limit).

gemini_summarize_files

File-based summarization optimized for @filename syntax (800,000 char limit).

Key Advantages over :

• 2x Higher Limit: 800K vs 400K characters for large codebases

• @filename Optimized: Purpose-built for direct file reading

• Token Efficiency: 50-70% improvement with lightweight prompts

• Enterprise Scale: Handles massive multi-directory projects

gemini_eval_plan

Evaluate Claude Code implementation plans (500,000 char limit).

gemini_review_code

Review specific code suggestions with detailed analysis (300,000 char limit).

gemini_verify_solution

Comprehensive verification of complete solutions (800,000 char limit).

Conversation Tools (5)

gemini_start_conversation

Start a new conversation with ID for stateful interactions.

gemini_continue_conversation

Continue an existing conversation with context history.

gemini_list_conversations

List active conversations with metadata.

gemini_clear_conversation

Clear/delete a specific conversation.

gemini_conversation_stats

Get conversation system statistics and health.

Specialized Code Review Tools (3)

gemini_code_review

Comprehensive code analysis with structured output (NEW).

gemini_extract_structured

Extract structured data using JSON schemas (NEW).

gemini_git_diff_review

Analyze git diffs with contextual feedback (NEW).

Content Comparison Tools (1)

gemini_content_comparison

Advanced multi-source content comparison and analysis (NEW).

AI Collaboration Tools (1)

gemini_ai_collaboration

Enhanced multi-platform AI collaboration with cross-platform capabilities.

Complete Parameter Reference for gemini_ai_collaboration

Available Collaboration Modes:

• sequential - Progressive refinement through ordered analysis pipeline

• debate - Multi-round discussions with consensus building

• validation - Cross-platform validation with conflict resolution

Available Debate Styles (for debate mode):

• constructive (default) - Focus on building understanding rather than winning arguments

• adversarial - Challenge assumptions and arguments rigorously

• collaborative - Work together to explore topics comprehensively

• socratic - Use questioning to explore underlying assumptions

• devil_advocate - Deliberately argue for challenging positions

Universal Parameters:

• collaboration_mode (required): sequential | debate | validation

• content (required): Content to be analyzed/processed

• models (optional): Comma-separated list of AI models (auto-selected if not provided)

• context (optional): Additional context for collaboration

• conversation_id (optional): For stateful conversation history

• budget_limit (optional): USD cost limit for OpenRouter models

Sequential Mode Parameters:

• pipeline_stages (optional): Comma-separated stages (auto-generated if not provided)

• handoff_criteria (optional): completion_of_stage | quality_threshold | consensus_reached | time_based

• quality_gates (optional): none | basic | standard | strict | comprehensive

• focus (optional): Focus area (default: "progressive refinement")

Debate Mode Parameters:

• rounds (optional): Number of debate rounds (1-10, default: 3)

• debate_style (optional): See debate styles above (default: "constructive")

• convergence_criteria (optional): substantial_agreement | consensus | majority_view | all_viewpoints

• focus (optional): Focus area (default: "comprehensive analysis")

Validation Mode Parameters:

• validation_criteria (optional): Comma-separated criteria (auto-generated if not provided)

• confidence_threshold (optional): 0.0-1.0 (default: 0.7)

• consensus_method (optional): simple_majority | weighted_majority | unanimous | supermajority | expert_panel

• conflict_resolution (optional): ignore | flag_only | detailed_analysis | additional_validation | expert_arbitration

Advanced Usage Examples

Different Debate Styles:

Sequential Pipeline Examples:

Validation Examples:

Auto-Selection Behavior: When models parameter is not provided, the function automatically selects appropriate models:

• Sequential: "gemini-2.5-flash,openai/gpt-4.1-nano,anthropic/claude-3-haiku"

• Debate: "gemini-2.5-flash,openai/gpt-4.1-mini,anthropic/claude-3-haiku"

• Validation: "gemini-2.5-flash,openai/gpt-4.1-nano,anthropic/claude-3-haiku"

OpenRouter Tools (6)

gemini_test_openrouter

Test OpenRouter connectivity and client functionality.

gemini_openrouter_opinion

Get responses from any of 400+ AI models via OpenRouter with @filename support.

gemini_openrouter_models

List all available OpenRouter models (400+) with advanced filtering and output options.

gemini_cross_model_comparison

Compare responses across Gemini CLI and OpenRouter models with @filename support.

gemini_openrouter_usage_stats

Get OpenRouter usage statistics and costs for the current session.

gemini_cross_model_comparison

Compare responses across Gemini CLI and OpenRouter models with @filename support.

📦 Installation

Prerequisites

• Python 3.10+ - Required for MCP SDK compatibility

• Gemini CLI - Google's command-line tool for Gemini AI

• uv (recommended) or pip for package management

Linux Setup

macOS Setup

Alternative Installation (pip)

⚙️ MCP Client Configuration

Claude Code

Add the server using the Claude Code MCP command for user scope:

Use the -s or --scope flag to specify where the configuration is stored:

• local (default): Available only to you in the current project (was called project in older versions)

• project: Shared with everyone in the project via .mcp.json file

• user: Available to you across all projects (was called global in older versions)

Claude Desktop

Add the following to your Claude Desktop settings file:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/claude/claude_desktop_config.json

Configuration:

Important: Use absolute paths for both the Python executable and the mcp_server.py script.

Other MCP Clients

For other MCP-compatible clients, use the stdio transport with:

• Command: Path to Python executable in virtual environment

• Arguments: Path to mcp_server.py

• Transport: stdio (standard input/output)

🎯 Usage Examples

Basic Operations

Simple Q&A:

File Analysis:

Code Execution:

Dual-AI Workflow Examples

The dual-AI workflow enables powerful collaboration between Claude Code and Gemini AI:

1. Plan Evaluation

2. Code Review During Development

3. Complete Solution Verification

Advanced Usage Patterns

Large Codebase Analysis:

Performance Analysis:

Security Assessment:

Specialized Code Review Examples (NEW)

Structured Code Analysis:

Schema-Based Data Extraction:

Git Diff Analysis:

Multi-Source Content Comparison:

⚡ Advanced Features

Dynamic Token Limits

Each tool has optimized character limits based on typical use cases:

Model-Aware Scaling

Limits automatically scale based on the selected model's capabilities:

• gemini-2.5-pro: 100% of limits (best quality)

• gemini-2.5-flash: 100% of limits (speed optimized)

• gemini-1.5-pro: 80% of limits (stable performance)

• gemini-1.5-flash: 60% of limits (speed focused)

• gemini-1.0-pro: 40% of limits (legacy compatibility)

Automatic Model Fallback

When quota limits are exceeded, the server automatically falls back from premium to standard models:

This ensures continuous operation during high-usage periods without user intervention.

OpenRouter Multi-Model Integration

Access to 400+ AI models from 20+ providers including OpenAI, Anthropic, Meta, Google, and more:

Key Benefits:

• Model Variants: Optimization options (:free, :nitro, :floor, :online) for cost, speed, and capabilities

• Cost Management: Built-in usage tracking with daily limits and warnings

• Cross-Platform Comparison: Compare responses between Gemini CLI and OpenRouter models

• Enhanced @filename Support: Intelligent large file handling for 200K+ token support

Popular Models Available:

• OpenAI: gpt-4.1-nano, gpt-4.1-mini, gpt-4.1,gpt-4o, gpt-4o-mini, gpt-3.5-turbo

• Anthropic: claude-sonnet-4, claude-3-haiku, claude-opus-4

• Meta: llama-3.2-11b-vision-instruct, llama-3.1-405b-instruct

• Google: gemini-2.5-pro, gemini-2.5-flash (via OpenRouter)

• Free Options: Multiple free model variants available

Conversation History Management

Stateful multi-turn conversations with persistent context:

Key Features:

• Redis-Backed Storage: Scalable conversation storage with graceful memory fallback

• Cross-Platform Support: Works seamlessly with both Gemini CLI and OpenRouter models

• Automatic Context Building: Intelligent context assembly respecting token limits

• Conversation Pruning: Automatic message and token limit management

• Configurable Expiration: Automatic cleanup with customizable retention periods

Advanced Caching

TTL-Based Caching:

• Help/version commands: 30 minutes

• Prompt results: 5 minutes

• Template loading: 30 minutes

Cache Features:

• Atomic operations prevent race conditions

• Memory limits prevent unbounded growth

• Automatic cleanup and expiration

• Cache hit/miss metrics tracking

@filename Syntax Support

32 of the 33 tools support Gemini CLI's native @filename syntax for optimal token efficiency. OpenRouter tools include enhanced large file handling:

Benefits:

• 50-70% token efficiency improvement for Gemini CLI tools

• Direct file reading by Gemini CLI

• Intelligent large file handling for OpenRouter (200K+ token support)

• Multiple processing strategies: full, chunk, summarize, auto

• No intermediate processing overhead

• Preserves full context window utilization

Template System Benefits

The modular template system provides significant advantages for enterprise deployments:

📈 Maintainability:

• Function Size Reduction: ~70% average reduction in function complexity

• Separation of Concerns: Template content isolated from business logic

• Single Responsibility: Each template serves a specific AI workflow purpose

• Version Control: Template changes tracked independently

⚡ Performance:

• TTL Caching: 30-minute cache for template loading reduces I/O overhead

• Memory Efficiency: Templates loaded once and reused across requests

• Response Time: Faster tool execution with cached template access

• Resource Optimization: Reduced filesystem access for repeated operations

🔧 Development Experience:

• Modular Architecture: Each dual-AI workflow tool has dedicated templates

• Easy Customization: Templates can be modified without touching core logic

• Testing: Templates can be unit tested independently

• Documentation: Self-documenting template structure with clear organization

⚙️ Configuration

Environment Variables

The server supports extensive configuration through environment variables:

Core Configuration

Retry Configuration

Tool-Specific Limits

Model Fallback

Rate Limiting

OpenRouter Configuration

Conversation Management

Cloudflare AI Gateway Integration (Optional)

Enterprise Monitoring (Optional)

Security Configuration (Advanced)

Configuration Examples

Standard Development:

With OpenRouter (400+ Models):

Full Enterprise Setup:

High-Performance Setup:

Debug Configuration:

Response Formats

JSON Format (Default)

Text Format

🚀 Performance

Performance Characteristics

Operation Times:

• Fast operations (help, version, metrics): < 2 seconds

• Medium operations (simple prompts): 2-10 seconds

• Complex operations (file analysis, code review): 10-60 seconds

• Large analysis (enterprise codebases): 1-5 minutes

• OpenRouter requests: 2-15 seconds (varies by model)

• Conversation context loading: < 1 second (with Redis)

Concurrency:

• Async architecture supports 1,000-10,000+ concurrent requests

• 10-100x concurrency improvement with lock-free cache operations

• Memory-efficient single-threaded design

• Non-blocking I/O operations across all 33 tools

Memory Usage:

• Base server: 15-30MB (optimized for enterprise features)

• Per operation: 2-8MB average (varies by tool complexity)

• Bounded caches prevent memory leaks with automatic cleanup

• O(1) rate limiting algorithms with memory leak protection

• Redis-backed conversation storage scales independently

Total Lines of Code: ~15,000+ lines across 83 modules

Cache Effectiveness:

• Help/version commands: 95-99% hit rate

• Prompt results: 60-80% hit rate for repeated operations

• Template loading: 90-95% hit rate (30-minute TTL)

• OpenRouter model discovery: 98% hit rate

• Conversation context: 85-95% hit rate with Redis

Performance Optimization

For High-Throughput Scenarios:

For Large Content Processing:

For Development Speed:

Monitoring

Use the gemini_metrics tool to monitor server performance:

Key Metrics:

• Commands executed and success rate across all 33 tools

• Average latency and throughput per tool category

• Cache hit rates and effectiveness (4 cache types)

• Error rates and types with detailed classification

• Model usage and fallback statistics (Gemini + OpenRouter)

• Memory usage and resource utilization

• OpenRouter cost tracking and usage statistics

• Conversation system performance and storage metrics

• Security pattern detection and rate limiting effectiveness

🧪 Testing

Quick Validation

Test Server Import:

Test Gemini CLI Integration:

MCP Inspector Testing

Test the server with the official MCP development tools:

This opens an interactive interface to test all MCP tools directly.

Manual Testing

Test Basic Functionality:

Test Prompt Functionality:

Production Readiness

The server has been comprehensively tested with:

• 2,500+ test cases across 6 specialized test files with descriptive naming

• Complete security validation covering all 22 critical security fixes with attack simulation

• Performance benchmarking with concurrency stress testing and memory leak detection

• Monitoring integration testing with graceful degradation validation

• @filename syntax validation with real files across 32 of 33 tools

• OpenRouter integration testing with 400+ model compatibility validation

• AI Collaboration testing with 92.9% success rate and production enhancements

• Conversation system testing with Redis storage and context management

• Specialized code review testing for new analysis tools

• Error handling and edge cases for enterprise deployment scenarios

🔧 Troubleshooting

Common Issues

"Tool 'gemini_cli' not found"

Cause: MCP client can't connect to server or server isn't running.

Solutions:

1. Verify absolute paths in MCP client configuration

2. Check that virtual environment is activated

3. Test server manually: python mcp_server.py

4. Check client logs for connection errors

"Gemini CLI not found"

Cause: Gemini CLI not installed or not in PATH.

Solutions:

1. Install Gemini CLI: npm install -g @google-ai/gemini-cli

2. Verify installation: gemini --version

3. Set custom path: export GEMINI_COMMAND_PATH=/path/to/gemini

Authentication Errors

Cause: Gemini API key not configured or invalid.

Solutions:

1. Configure API key: gemini config set api_key YOUR_API_KEY

2. Verify key validity: gemini --version

3. Check API quota and billing status

Rate Limit Exceeded

Cause: Too many requests in short time period.

Solutions:

1. Wait for rate limit window to reset

2. Increase limits: export GEMINI_RATE_LIMIT_REQUESTS=500

3. Use faster model: Switch to gemini-2.5-flash

Large Content Failures

Cause: Content exceeds tool-specific character limits.

Solutions:

1. Check content size: wc -c your_file.txt

2. Increase limits: export GEMINI_EVAL_LIMIT=1000000

3. Use chunking strategy for very large content

4. Use gemini_summarize_files for file-based analysis

Server Won't Start

Diagnostic Steps:

1. Check Python version: python --version (must be 3.10+)

2. Verify dependencies: pip list | grep mcp

3. Test imports: python -c "import mcp"

4. Check logs: GEMINI_LOG_LEVEL=DEBUG python mcp_server.py

Performance Issues

Optimization Steps:

1. Monitor metrics: Use gemini_metrics() tool

2. Check cache hit rates (should be >80% for repeated operations)

3. Reduce logging: export GEMINI_LOG_LEVEL=WARNING

4. Optimize timeouts: export GEMINI_TIMEOUT=120

Debug Mode

Enable comprehensive debugging:

This provides detailed information about:

• Command execution and arguments

• Cache operations and hit rates

• Error details and stack traces

• Performance metrics and timing

• Model fallback behavior

Getting Help

If you encounter issues not covered here:

1. Check server logs for detailed error messages

2. Verify Gemini CLI works independently: gemini --help

3. Test with simple commands first: gemini_version()

4. Monitor metrics for performance insights: gemini_metrics()

5. Check environment variables for correct configuration

📄 Requirements

System Requirements

• Python: 3.10 or higher

• Operating System: Linux, macOS, or Windows

• Memory: 512MB minimum, 2GB recommended

• Disk Space: 100MB for installation

• Network: Internet connection for Gemini API access

Python Dependencies

Optional Dependencies

External Dependencies

• Gemini CLI: Google's command-line interface for Gemini AI

• Node.js: Required for Gemini CLI installation (if using npm)

Star History