Gemini Bridge

🚀 Gemini Bridge

Gemini Bridge is a lightweight MCP server that enables AI coding assistants to interact with Google's Gemini AI via the official CLI, offering seamless integration with various MCP - compatible clients.

🚀 Quick Start

Prerequisites

1. Install Gemini CLI:

   npm install -g @google/gemini-cli
   

2. Authenticate with Gemini:

   gemini auth login
   

3. Verify installation:

   gemini --version
   

Installation

🎯 Recommended: PyPI Installation

# Install from PyPI
pip install gemini-bridge

# Add to Claude Code with uvx (recommended)
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

Alternative: From Source

# Clone the repository
git clone https://github.com/shelakh/gemini-bridge.git
cd gemini-bridge

# Build and install locally
uvx --from build pyproject-build
pip install dist/*.whl

# Add to Claude Code
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

Development Installation

# Clone and install in development mode
git clone https://github.com/shelakh/gemini-bridge.git
cd gemini-bridge
pip install -e .

# Add to Claude Code (development)
claude mcp add gemini-bridge-dev -s user -- python -m src

✨ Features

• Direct Gemini CLI Integration: Zero API costs using official Gemini CLI
• Simple MCP Tools: Two core functions for basic queries and file analysis
• Stateless Operation: No sessions, caching, or complex state management
• Production Ready: Robust error handling with configurable 60 - second timeouts
• Minimal Dependencies: Only requires mcp>=1.0.0 and Gemini CLI
• Easy Deployment: Support for both uvx and traditional pip installation
• Universal MCP Compatibility: Works with any MCP - compatible AI coding assistant

🌐 Multi - Client Support

Gemini Bridge works with any MCP - compatible AI coding assistant - the same server supports multiple clients through different configuration methods.

Supported MCP Clients

• Claude Code ✅ (Default)
• Cursor ✅
• VS Code ✅
• Windsurf ✅
• Cline ✅
• Void ✅
• Cherry Studio ✅
• Augment ✅
• Roo Code ✅
• Zencoder ✅
• Any MCP - compatible client ✅

Configuration Examples

# Recommended installation
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

# Development installation
claude mcp add gemini-bridge-dev -s user -- python -m src

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

{
  "servers": {
    "gemini-bridge": {
      "type": "stdio",
      "command": "uvx",
      "args": ["gemini-bridge"]
    }
  }
}

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

"augment.advanced": { 
  "mcpServers": [ 
    { 
      "name": "gemini-bridge", 
      "command": "uvx", 
      "args": ["gemini-bridge"],
      "env": {}
    }
  ]
}

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

{
  "command": "uvx",
  "args": ["gemini-bridge"],
  "env": {}
}

{
  "command": "gemini-bridge",
  "args": [],
  "env": {}
}

{
  "command": "python",
  "args": ["-m", "src"],
  "env": {},
  "cwd": "/path/to/gemini-bridge"
}

{
  "command": "npx",
  "args": ["gemini-bridge"],
  "env": {}
}

Universal Usage

Once configured with any client, use the same two tools:

1. Ask general questions: "What authentication patterns are used in this codebase?"
2. Analyze specific files: "Review these auth files for security issues"

The server implementation is identical - only the client configuration differs!

⚙️ Configuration

Timeout Configuration

By default, Gemini Bridge uses a 60 - second timeout for all CLI operations. For longer queries (large files, complex analysis), you can configure a custom timeout using the GEMINI_BRIDGE_TIMEOUT environment variable.

Example configurations:

# Add with custom timeout (120 seconds)
claude mcp add gemini-bridge -s user --env GEMINI_BRIDGE_TIMEOUT=120 -- uvx gemini-bridge

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {
        "GEMINI_BRIDGE_TIMEOUT": "120"
      }
    }
  }
}

Timeout Options:

• Default: 60 seconds (if not configured)
• Range: Any positive integer (seconds)
• Recommended: 120 - 300 seconds for large file analysis
• Invalid values: Fall back to 60 seconds with warning

💻 Usage Examples

Basic Usage

# Simple research query
consult_gemini(
    query="What authentication patterns are used in this project?",
    directory="/Users/dev/my-project"
)

Advanced Usage

# Analyze specific files
consult_gemini_with_files(
    query="Review these files and suggest security improvements",
    directory="/Users/dev/my-project",
    files=["src/auth.py", "src/middleware.py"],
    model="pro"
)

# Compare multiple implementation files
consult_gemini_with_files(
    query="Compare these database implementations and recommend the best approach",
    directory="/Users/dev/my-project",
    files=["src/db/postgres.py", "src/db/sqlite.py", "src/db/redis.py"]
)

🏗️ Architecture

Core Design

• CLI - First: Direct subprocess calls to gemini command
• Stateless: Each tool call is independent with no session state
• Fixed Timeout: 60 - second maximum execution time
• Simple Error Handling: Clear error messages with fail - fast approach

Project Structure

gemini-bridge/
├── src/
│   ├── __init__.py              # Entry point
│   ├── __main__.py              # Module execution entry point
│   └── mcp_server.py            # Main MCP server implementation
├── .github/                     # GitHub templates and workflows
├── pyproject.toml              # Python package configuration
├── README.md                   # This file
├── CONTRIBUTING.md             # Contribution guidelines
├── CODE_OF_CONDUCT.md          # Community standards
├── SECURITY.md                 # Security policies
├── CHANGELOG.md               # Version history
└── LICENSE                    # MIT license

🔧 Technical Details

Local Testing

# Install in development mode
pip install -e .

# Run directly
python -m src

# Test CLI availability
gemini --version

Integration with Claude Code

The server automatically integrates with Claude Code when properly configured through the MCP protocol.

🔍 Troubleshooting

CLI Not Available

# Install Gemini CLI
npm install -g @google/gemini-cli

# Authenticate
gemini auth login

# Test
gemini --version

Connection Issues

• Verify Gemini CLI is properly authenticated
• Check network connectivity
• Ensure Claude Code MCP configuration is correct
• Check that the gemini command is in your PATH

Common Error Messages

• "CLI not available": Gemini CLI is not installed or not in PATH
• "Authentication required": Run gemini auth login
• "Timeout after 60 seconds": Query took too long, try breaking it into smaller parts

🤝 Contributing

We welcome contributions from the community! Please read our Contributing Guidelines for details on how to get started.

Quick Contributing Guide

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 - see the LICENSE file for details.

🔄 Version History

See CHANGELOG.md for detailed version history.

🆘 Support

• Issues: Report bugs or request features via GitHub Issues
• Discussions: Join the community discussion
• Documentation: Additional docs can be created in the docs/ directory

Focus: A simple, reliable bridge between Claude Code and Gemini AI through the official CLI.