Skip to main content
Glama
deenesjakoruzh
eLyiN

gemini-bridge

by eLyiN
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Gemini Bridge

CI Status PyPI Version MIT License Python 3.10+ MCP Compatible Gemini CLI

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

  • Three MCP Tools: Basic queries, file analysis, and web search capabilities

  • 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

  • Modern Python: Uses pathlib and modern type hints (Python 3.10+)

Related MCP server: Globalping

🚀 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

# 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

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

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

Add to your Windsurf MCP configuration:

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

  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": {}
    }
  }
}

Go to: Settings → MCP → Add MCP Server

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

  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

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": {}
    }
  ]
}

  1. Go to Settings → MCP Servers → Edit Global Config

  2. Add to mcp_settings.json:

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

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

  2. Add configuration:

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

  1. Hit the Install button

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": {}
}

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)

  • 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

  • model (string, optional): Model to use - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", or "auto" (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", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", or "auto" (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.

web_search

Ask Gemini queries with web search context. Uses Gemini CLI's automatic web search when the model determines it's needed. Best-effort functionality - not guaranteed for every query.

Parameters:

  • query (string): Search query or question to look up on the web

  • directory (string): Working directory for command execution

  • model (string, optional): Model to use - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", or "auto" (default: "flash")

  • timeout_seconds (int, optional): Override the execution timeout for this request

Example:

web_search(
    query="latest Python version and new features",
    model="flash"
)

📋 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 improvements",
    directory="/Users/dev/my-project",
    files=["src/auth.py", "src/middleware.py"],
    model="pro"
)

Multi-file Analysis

# 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"],
    mode="at_command"
)

Web Search

# Get current information from the web
web_search(
    query="latest Python version and new features in 3.13",
    model="flash"
)

Large File Safeguards

  • Inline transfers cap at ~256 KB per file and ~512 KB per request to avoid hangs.

  • Oversized files are truncated to head/tail snippets with a warning in the MCP response.

  • Tune the caps with environment variables (GEMINI_BRIDGE_MAX_INLINE_TOTAL_BYTES, etc.) or prefer mode="at_command" for bigger payloads.

🏗️ Architecture

Core Design

  • CLI-First: Direct subprocess calls to gemini command

  • Stateless: Each tool call is independent with no session state

  • Adaptive Timeout: Defaults to 60 seconds but overridable per request or via env var

  • Attachment Guardrails: Inline mode enforces lightweight limits; @ mode delegates to Gemini CLI tooling

  • 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

🔧 Development

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.

Available Tools

3 tools
consult_geminiA

Send a query directly to the Gemini CLI.

Args:
    query: Prompt text forwarded verbatim to the CLI.
    directory: Working directory used for command execution.
    model: Optional model alias (``flash``, ``pro``) or full Gemini model id.
    timeout_seconds: Optional per-call timeout override in seconds.

Returns:
    Gemini's response text or an explanatory error string.
ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
directoryYes
modelNo
timeout_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses that the query is 'forwarded verbatim to the CLI', explains optional parameters (model, timeout), and describes the return value as 'Gemini's response text or an explanatory error string'. This provides sufficient behavioral context for a query tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with Args/Returns sections and no extraneous content. It is concise but includes necessary parameter details. Minor tightening could improve it, but overall effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (4 params, 2 required) and presence of an output schema (implied by return description), the description covers the key behavioral aspects. It explains inputs, optional overrides, and return value, making it complete enough for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the description carries the burden. It explains all four parameters: query (prompt text), directory (working directory), model (optional alias or ID), timeout_seconds (per-call override). This adds meaning beyond the schema's raw type definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Send a query directly to the Gemini CLI', specifying the verb (send) and resource (Gemini CLI). The name 'consult_gemini' and sibling tools 'consult_gemini_with_files' and 'web_search' help distinguish its purpose as a direct query without file context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly mention when to use this tool vs. 'consult_gemini_with_files' or 'web_search'. It only implies usage for direct queries without files, lacking alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

consult_gemini_with_filesA

Send a query to the Gemini CLI with file context.

Args:
    query: Prompt text forwarded to the CLI.
    directory: Working directory used for resolving relative file paths.
    files: Relative or absolute file paths to include alongside the prompt.
    model: Optional model alias (``flash``, ``pro``) or full Gemini model id.
    timeout_seconds: Optional per-call timeout override in seconds.
    mode: ``"inline"`` streams truncated snippets; ``"at_command"`` emits
        ``@path`` directives so Gemini CLI resolves files itself.

Returns:
    Gemini's response or an explanatory error string with any warnings.
ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
directoryYes
filesNo
modelNo
timeout_secondsNo
modeNoinline

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It explains parameter purposes, mode behavior ('inline' vs 'at_command'), and return type. However, it omits side effects, auth needs, or rate limits, which are minor for a query tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: a crisp one-liner, a bulleted Args list, and a Returns statement. Every sentence is informative with no redundancy, achieving conciseness without sacrificing completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters, no annotations, and presence of output schema, the description covers all essential aspects: parameter definitions, mode options, and return value. It is fully sufficient for tool invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It does so excellently by detailing each of the 6 parameters, including defaults and mode semantics, adding significant value beyond raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Send a query' and the resource 'Gemini CLI with file context', distinguishing it from siblings consult_gemini (likely without files) and web_search (different domain).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lacks explicit guidance on when to use this tool over siblings. While it implies file context as differentiator, it does not state when to prefer consult_gemini or web_search, leaving some ambiguity for agent selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev1.3.0
    • Addedweb_search
  2. 2 tool updatesv1.0.0
    • Changedconsult_gemini1 field changed
      • addedInput schema / properties / timeout_seconds
        Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Timeout Seconds"
+}
    • Changedconsult_gemini_with_files2 fields changed
      • addedInput schema / properties / mode
        Added value: +{
+  "default": "inline",
+  "title": "Mode",
+  "type": "string"
+}
      • addedInput schema / properties / timeout_seconds
        Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Timeout Seconds"
+}
  3. 2 tool updates
    • First observedconsult_gemini
    • First observedconsult_gemini_with_files
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: plain query, query with file context, and web search. There is no overlap or ambiguity between them.

Naming Consistency4/5

Two tools share the 'consult_gemini' prefix with suffixes, but 'web_search' breaks the pattern. The naming is mostly consistent but has a minor deviation.

Tool Count5/5

With 3 tools, the set is lean and well-scoped for a Gemini CLI bridge. Each tool adds essential functionality without redundancy.

Completeness4/5

Core interactions (simple query, file-augmented, web search) are covered. Missing features like streaming or tool execution are non-critical for this server's scope.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/eLyiN/gemini-bridge'

If you have feedback or need assistance with the MCP directory API, please join our Discord server