gemini-bridge
Gemini Bridge
一个轻量级的 MCP(模型上下文协议)服务器,使 AI 编码助手能够通过官方 CLI 与 Google Gemini AI 进行交互。适用于 Claude Code、Cursor、VS Code 以及其他兼容 MCP 的客户端。专为简洁、可靠和无缝集成而设计。
✨ 特性
直接集成 Gemini CLI:使用官方 Gemini CLI,零 API 成本
三个 MCP 工具:基础查询、文件分析和网页搜索功能
无状态操作:无会话、缓存或复杂的状态管理
生产就绪:强大的错误处理,支持可配置的 60 秒超时
最小依赖:仅需
mcp>=1.0.0和 Gemini CLI轻松部署:支持 uvx 和传统的 pip 安装
通用 MCP 兼容性:适用于任何兼容 MCP 的 AI 编码助手
现代 Python:使用 pathlib 和现代类型提示(Python 3.10+)
Related MCP server: Globalping
🚀 快速开始
前置要求
安装 Gemini CLI:
npm install -g @google/gemini-cli进行 Gemini 身份验证:
gemini auth login验证安装:
gemini --version
安装
🎯 推荐:PyPI 安装
# Install from PyPI
pip install gemini-bridge
# Add to Claude Code with uvx (recommended)
claude mcp add gemini-bridge -s user -- uvx gemini-bridge替代方案:从源码安装
# 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开发安装
# 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🌐 多客户端支持
Gemini Bridge 适用于任何兼容 MCP 的 AI 编码助手 - 同一个服务器可以通过不同的配置方法支持多个客户端。
支持的 MCP 客户端
Claude Code ✅ (默认)
Cursor ✅
VS Code ✅
Windsurf ✅
Cline ✅
Void ✅
Cherry Studio ✅
Augment ✅
Roo Code ✅
Zencoder ✅
任何兼容 MCP 的客户端 ✅
配置示例
# 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全局配置 (~/.cursor/mcp.json):
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}项目特定配置 (.cursor/mcp.json 在您的项目中):
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}前往:Settings → Cursor Settings → MCP → Add new global MCP server
配置 (.vscode/mcp.json 在您的工作区中):
{
"servers": {
"gemini-bridge": {
"type": "stdio",
"command": "uvx",
"args": ["gemini-bridge"]
}
}
}替代方案:通过扩展程序
打开扩展视图 (Ctrl+Shift+X)
搜索 MCP 扩展
使用命令添加自定义服务器:
uvx gemini-bridge
添加到您的 Windsurf MCP 配置中:
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}打开 Cline 并点击顶部导航栏的 MCP Servers
选择 Installed 选项卡 → Advanced MCP Settings
添加到
cline_mcp_settings.json:
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}前往:Settings → MCP → Add MCP Server
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}导航至 Settings → MCP Servers → Add Server
填写服务器详细信息:
Name:
gemini-bridgeType:
STDIOCommand:
uvxArguments:
["gemini-bridge"]
保存配置
使用 UI:
点击汉堡菜单 → Settings → Tools
点击 + Add MCP 按钮
输入命令:
uvx gemini-bridge名称:Gemini Bridge
手动配置:
"augment.advanced": {
"mcpServers": [
{
"name": "gemini-bridge",
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
]
}前往 Settings → MCP Servers → Edit Global Config
添加到
mcp_settings.json:
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}前往 Zencoder 菜单 (...) → Tools → Add Custom MCP
添加配置:
{
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}点击 Install 按钮
对于基于 pip 的安装:
{
"command": "gemini-bridge",
"args": [],
"env": {}
}对于开发/本地测试:
{
"command": "python",
"args": ["-m", "src"],
"env": {},
"cwd": "/path/to/gemini-bridge"
}对于 npm 风格的安装 (如果需要):
{
"command": "npx",
"args": ["gemini-bridge"],
"env": {}
}通用用法
一旦与任何客户端配置完成,即可使用相同的两个工具:
询问一般问题:“此代码库中使用了哪些身份验证模式?”
分析特定文件:“审查这些身份验证文件是否存在安全问题”
服务器实现是相同的 - 只有客户端配置不同!
⚙️ 配置
超时配置
默认情况下,Gemini Bridge 对所有 CLI 操作使用 60 秒的超时时间。对于更长的查询(大文件、复杂分析),您可以使用 GEMINI_BRIDGE_TIMEOUT 环境变量配置自定义超时时间。
配置示例:
# 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"
}
}
}
}超时选项:
默认:60 秒(如果未配置)
范围:任何正整数(秒)
单次调用覆盖:为任一工具提供
timeout_seconds以进行一次性扩展推荐:大文件分析建议 120-300 秒
无效值:回退到 60 秒并发出警告
🛠️ 可用工具
consult_gemini
用于简单查询的直接 CLI 桥接。
参数:
query(string):发送给 Gemini 的问题或提示directory(string):查询的工作目录model(string, 可选):使用的模型 - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", 或 "auto" (默认: "flash")timeout_seconds(int, 可选):覆盖此请求的执行超时时间
示例:
consult_gemini(
query="Find authentication patterns in this codebase",
directory="/path/to/project",
model="flash"
)consult_gemini_with_files
带有文件附件的 CLI 桥接,用于详细分析。
参数:
query(string):发送给 Gemini 的问题或提示directory(string):查询的工作目录files(list):相对于目录的文件路径列表model(string, 可选):使用的模型 - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", 或 "auto" (默认: "flash")timeout_seconds(int, 可选):覆盖此请求的执行超时时间mode(string, 可选):"inline"(默认,流式传输文件内容)或 "at_command"(让 Gemini CLI 自行解析@path引用)
示例:
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
)提示: 扫描大型树结构时,切换到 mode="at_command",以便 Gemini CLI 原生处理文件通配符和截断。
web_search
使用网页搜索上下文向 Gemini 提问。当模型确定需要时,使用 Gemini CLI 的自动网页搜索。尽力而为的功能 - 不保证每次查询都有效。
参数:
query(string):要在网页上查找的搜索查询或问题directory(string):命令执行的工作目录model(string, 可选):使用的模型 - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", 或 "auto" (默认: "flash")timeout_seconds(int, 可选):覆盖此请求的执行超时时间
示例:
web_search(
query="latest Python version and new features",
model="flash"
)📋 使用示例
基础代码分析
# Simple research query
consult_gemini(
query="What authentication patterns are used in this project?",
directory="/Users/dev/my-project"
)详细文件审查
# 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"],
mode="at_command"
)网页搜索
# Get current information from the web
web_search(
query="latest Python version and new features in 3.13",
model="flash"
)大文件保护措施
内联传输限制为每个文件约 256 KB,每个请求约 512 KB,以避免挂起。
超大文件会被截断为头部/尾部片段,并在 MCP 响应中发出警告。
使用环境变量(
GEMINI_BRIDGE_MAX_INLINE_TOTAL_BYTES等)调整上限,或对于更大的负载优先使用mode="at_command"。
🏗️ 架构
核心设计
CLI 优先:直接对
gemini命令进行子进程调用无状态:每个工具调用都是独立的,没有会话状态
自适应超时:默认为 60 秒,但可按请求或通过环境变量覆盖
附件护栏:内联模式强制执行轻量级限制;
@模式委托给 Gemini CLI 工具简单的错误处理:清晰的错误消息,采用快速失败方法
项目结构
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🔧 开发
本地测试
# Install in development mode
pip install -e .
# Run directly
python -m src
# Test CLI availability
gemini --version与 Claude Code 集成
当通过 MCP 协议正确配置后,服务器会自动与 Claude Code 集成。
🔍 故障排除
CLI 不可用
# Install Gemini CLI
npm install -g @google/gemini-cli
# Authenticate
gemini auth login
# Test
gemini --version连接问题
验证 Gemini CLI 是否已正确验证
检查网络连接
确保 Claude Code MCP 配置正确
检查
gemini命令是否在您的 PATH 中
常见错误消息
"CLI not available":未安装 Gemini CLI 或不在 PATH 中
"Authentication required":运行
gemini auth login"Timeout after 60 seconds":查询耗时过长,尝试将其拆分为较小的部分
🤝 贡献
我们欢迎社区的贡献!请阅读我们的 贡献指南 以了解如何开始。
快速贡献指南
Fork 本仓库
创建功能分支
进行更改
如果适用,添加测试
提交拉取请求
📄 许可证
本项目采用 MIT 许可证 - 有关详细信息,请参阅 LICENSE 文件。
🔄 版本历史
有关详细的版本历史,请参阅 CHANGELOG.md。
🆘 支持
问题:通过 GitHub Issues 报告错误或请求功能
讨论:加入社区讨论
文档:可以在
docs/目录中创建其他文档
重点:通过官方 CLI 在 Claude Code 和 Gemini AI 之间建立一个简单、可靠的桥梁。
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.-