gemini-bridge
Gemini Bridge provides MCP tools to interact with Google's Gemini AI through the official CLI.
Run direct queries to Gemini using
consult_geminiwith a query and working directory, optionally choosing a model and timeout.Analyze files by sending prompts plus file paths via
consult_gemini_with_files, using inline snippets orat_commandfor CLI-side file resolution.Perform web-search-assisted queries via
web_search, with best-effort automatic web search by Gemini.Use model aliases such as flash, pro, flash-lite, auto, etc., and override the default 60-second timeout per call or via env var.
Integrate with MCP-compatible clients like Claude Code, Cursor, VS Code, and others.
Benefit from stateless operation, error handling, and safeguards for large inline file transfers.
Enables AI coding assistants to interact with Google's Gemini AI through the official CLI, providing tools for general queries and file analysis with support for both flash and pro models
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gemini-bridgeexplain this Python function: def calculate_total(items): return sum(item['price'] for item in items)"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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>=2,<3and Gemini CLIEasy 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
Install Gemini CLI:
npm install -g @google/gemini-cliAuthenticate with Gemini:
gemini auth loginVerify 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-bridgeAlternative: 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-bridgeDevelopment 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 srcGlobal 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
Open Extensions view (Ctrl+Shift+X)
Search for MCP extensions
Add custom server with command:
uvx gemini-bridge
Add to your Windsurf MCP configuration:
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}Open Cline and click MCP Servers in the top navigation
Select Installed tab β Advanced MCP Settings
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": {}
}
}
}Navigate to Settings β MCP Servers β Add Server
Fill in the server details:
Name:
gemini-bridgeType:
STDIOCommand:
uvxArguments:
["gemini-bridge"]
Save the configuration
Using the UI:
Click hamburger menu β Settings β Tools
Click + Add MCP button
Enter command:
uvx gemini-bridgeName: Gemini Bridge
Manual Configuration:
"augment.advanced": {
"mcpServers": [
{
"name": "gemini-bridge",
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
]
}Go to Settings β MCP Servers β Edit Global Config
Add to
mcp_settings.json:
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}Go to Zencoder menu (...) β Tools β Add Custom MCP
Add configuration:
{
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}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:
Ask general questions: "What authentication patterns are used in this codebase?"
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_secondsto either tool for one-off extensionsRecommended: 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 Geminidirectory(string): Working directory for the querymodel(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 Geminidirectory(string): Working directory for the queryfiles(list): List of file paths relative to the directorymodel(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 requestmode(string, optional): Either"inline"(default) to stream file contents or"at_command"to let Gemini CLI resolve@pathreferences 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 webdirectory(string): Working directory for command executionmodel(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 prefermode="at_command"for bigger payloads.
ποΈ Architecture
Core Design
CLI-First: Direct subprocess calls to
geminicommandStateless: 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 toolingSimple 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 --versionIntegration 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 --versionConnection Issues
Verify Gemini CLI is properly authenticated
Check network connectivity
Ensure Claude Code MCP configuration is correct
Check that the
geminicommand 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
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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 toolsconsult_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.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | ||
| query | Yes | ||
| directory | Yes | ||
| timeout_seconds | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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: File paths to include alongside the prompt. Paths must resolve
inside ``directory``; entries pointing outside it are skipped.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | inline | |
| files | No | ||
| model | No | ||
| query | Yes | ||
| directory | Yes | ||
| timeout_seconds | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that files outside the working directory are silently skipped, that errors are returned as explanatory strings with warnings, and that per-call timeouts are possible. It stops short of stating auth/network prerequisites or what triggers truncation limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded one-line summary followed by structured Args/Returns sections; each parameter line earns its place. The Returns block partially duplicates the output schema but is short enough not to be wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter external-CLI tool, all parameters and the path-safety rule are covered, and an output schema exists so return values need little prose. The main gap is the absent routing guidance versus consult_gemini and no discussion of limits when many/large files are passed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the schema even lacks enum metadata, so the description must compensate fully β and it does, defining mode values ('inline' streams truncated snippets vs 'at_command' emits @path directives), model aliases (flash/pro), the path-resolution constraint on files, and the purpose of directory and timeout overrides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Send a query to the Gemini CLI with file context'), which clearly separates it from the sibling consult_gemini that lacks file context. It is clear, but it never explicitly contrasts itself with that sibling or names when file context is needed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use/when-not guidance or named alternative is given; the agent must infer from the tool name that files-bearing queries belong here rather than in consult_gemini. The mode explanation implies usage patterns but does not state selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
web_searchA
Ask Gemini queries with web search context.
Note: This uses Gemini CLI's automatic web search capability.
The model determines when to search based on query context.
Best-effort web search - not guaranteed for every query.
Args:
query: Search query or question to look up on the web
directory: Working directory for command execution
model: Optional model alias (flash, pro, or custom)
timeout_seconds: Optional per-call timeout override in seconds
Returns:
Gemini's response with potential web sources
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | ||
| query | Yes | ||
| directory | No | . | |
| timeout_seconds | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions automatic web search and best-effort nature, but omits details like rate limits, cost, or potential failure modes. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is front-loaded with purpose, followed by notes and args in a clear docstring format. Slightly verbose but well-structured; no redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. Description explains tool behavior, parameters, and limitations. Complete for a web search tool with given complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds meaning to all 4 parameters: query as search term, directory as working directory, model as optional alias, timeout as per-call override. This compensates well for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The tool name 'web_search' and description 'Ask Gemini queries with web search context' clearly state the purpose. It distinguishes from siblings (consult_gemini, consult_gemini_with_files) by explicitly mentioning web search context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explains that the model determines when to search and that it's best-effort, giving guidance on when to use and expectations. However, it does not explicitly state when not to use or mention alternatives.
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.
1 tool update
v1.3.0- Added
web_search
2 tool updates
v1.0.0- Changed
consult_gemini1 field changed- added
Input schema / properties / timeout_secondsAdded value: +{ + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Timeout Seconds" +}
- Changed
consult_gemini_with_files2 fields changed- added
Input schema / properties / modeAdded value: +{ + "default": "inline", + "title": "Mode", + "type": "string" +} - added
Input schema / properties / timeout_secondsAdded value: +{ + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Timeout Seconds" +}
2 tool updates
- First observed
consult_gemini - First observed
consult_gemini_with_files
TDQS
Scored across 3 tools
The three tools are mostly distinguishable: consult_gemini is plain, consult_gemini_with_files adds file context, and web_search adds search context. The overlap between the two consult_* tools is realβthey differ only by file argumentsβbut the file/web/plain split gives an agent a reasonable basis for selection.
Two tools follow a clean consult_gemini / consult_gemini_with_files pattern, and web_search is a readable verb_noun name. The only deviation is web_search not carrying the consult_ prefix, but it describes a genuinely different capability so it still reads consistently.
Three tools is well-scoped for a thin bridge to a single CLI. Each tool maps to a distinct query mode rather than padding the surface, though the small count sits at the lower edge of the ideal range.
For a Gemini CLI passthrough the surface covers the main workflows: plain queries, file-context queries, and web-grounded queries. Minor gaps exist (no streaming/session continuity or config/inspection tool), but agents can accomplish the core task set without dead ends.
Maintenance
Related MCP Connectors
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server for GLM chat completions using Zhipu AI models via AceDataCloud
Official MCP server for Agentwork β delegate tasks to AI agents with human-in-the-loop
Related MCP Servers
- FlicenseBqualityDmaintenanceA lightweight MCP server that provides a unified interface to various LLM providers including OpenAI, Anthropic, Google Gemini, Groq, DeepSeek, and Ollama.6739-

Globalpingofficial
FlicenseNot gradedqualityBmaintenanceRemote MCP server that gives LLMs access to run network commands64-- AlicenseAqualityFmaintenanceA lightweight MCP server that enables AI coding assistants to interact with Google's Gemini AI through the official CLI.3MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that lets Claude query Google's Gemini CLI as a sub-agent. Get second opinions, verify information, and cross-reference answers between AI models.-