Gemini Bridge

A lightweight MCP (Model Context Protocol) server that enables AI coding assistants to interact with Google's Gemini AI through the official CLI. Works with Claude Code, Cursor, VS Code, and other MCP-compatible clients. Designed for simplicity, reliability, and seamless integration.

✨ 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

🚀 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

🌐 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

<details> <summary><strong>Claude Code</strong> (Default)</summary>

# 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

</details> <details> <summary><strong>Cursor</strong></summary>

Global Configuration (~/.cursor/mcp.json):

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

Project-Specific (.cursor/mcp.json in your project):

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

Go to: Settings → Cursor Settings → MCP → Add new global MCP server

</details> <details> <summary><strong>VS Code</strong></summary>

Configuration (.vscode/mcp.json in your workspace):

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

Alternative: Through Extensions

1. Open Extensions view (Ctrl+Shift+X)
2. Search for MCP extensions
3. Add custom server with command: uvx gemini-bridge

</details> <details> <summary><strong>Windsurf</strong></summary>

Add to your Windsurf MCP configuration:

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

</details> <details> <summary><strong>Cline</strong> (VS Code Extension)</summary>

1. Open Cline and click MCP Servers in the top navigation
2. Select Installed tab → Advanced MCP Settings
3. Add to cline_mcp_settings.json:

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

</details> <details> <summary><strong>Void</strong></summary>

Go to: Settings → MCP → Add MCP Server

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

</details> <details> <summary><strong>Cherry Studio</strong></summary>

1. Navigate to Settings → MCP Servers → Add Server
2. Fill in the server details:
   • Name: gemini-bridge
   • Type: STDIO
   • Command: uvx
   • Arguments: ["gemini-bridge"]
3. Save the configuration

</details> <details> <summary><strong>Augment</strong></summary>

Using the UI:

1. Click hamburger menu → Settings → Tools
2. Click + Add MCP button
3. Enter command: uvx gemini-bridge
4. Name: Gemini Bridge

Manual Configuration:

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

</details> <details> <summary><strong>Roo Code</strong></summary>

1. Go to Settings → MCP Servers → Edit Global Config
2. Add to mcp_settings.json:

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

</details> <details> <summary><strong>Zencoder</strong></summary>

1. Go to Zencoder menu (...) → Tools → Add Custom MCP
2. Add configuration:

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

1. Hit the Install button

</details> <details> <summary><strong>Alternative Installation Methods</strong></summary>

For pip-based installations:

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

For development/local testing:

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

For npm-style installation (if needed):

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

</details>

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:

<details> <summary><strong>Claude Code</strong></summary>

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

</details> <details> <summary><strong>Manual Configuration (mcp_settings.json)</strong></summary>

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

</details>

Timeout Options:

• Default: 60 seconds (if not configured)
• Range: Any positive integer (seconds)
• Per-call override: Supply timeout_seconds to either tool for one-off extensions
• Recommended: 120-300 seconds for large file analysis
• Invalid values: Fall back to 60 seconds with warning

🛠️ Available Tools

consult_gemini

Direct CLI bridge for simple queries.

Parameters:

• query (string): The question or prompt to send to Gemini
• directory (string): Working directory for the query (default: current directory)
• model (string, optional): Model to use - "flash" or "pro" (default: "flash")
• timeout_seconds (int, optional): Override the execution timeout for this request

Example:

consult_gemini(
    query="Find authentication patterns in this codebase",
    directory="/path/to/project",
    model="flash"
)

consult_gemini_with_files

CLI bridge with file attachments for detailed analysis.

Parameters:

• query (string): The question or prompt to send to Gemini
• directory (string): Working directory for the query
• files (list): List of file paths relative to the directory
• model (string, optional): Model to use - "flash" or "pro" (default: "flash")
• timeout_seconds (int, optional): Override the execution timeout for this request
• mode (string, optional): Either "inline" (default) to stream file contents or "at_command" to let Gemini CLI resolve @path references itself

Example:

consult_gemini_with_files(
    query="Analyze these auth files and suggest improvements",
    directory="/path/to/project",
    files=["src/auth.py", "src/models.py"],
    model="pro",
    timeout_seconds=180
)

Tip: When scanning large trees, switch to mode="at_command" so the Gemini CLI handles file globbing and truncation natively.

📋 Usage Examples

Basic Code Analysis

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

Detailed File Review

# Analyze specific files
consult_gemini_with_files(
    query="Review these files and suggest security imp

---