Gemini Bridge

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

一个轻量级的 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: MCP Gemini API Server

🚀 快速开始

前置要求

安装 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-bridge
- Type: STDIO
- Command: uvx
- Arguments: ["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 之间建立一个简单、可靠的桥梁。

Gemini Bridge

✨ 特性

🚀 快速开始

前置要求

安装

🌐 多客户端支持

支持的 MCP 客户端

配置示例

通用用法

⚙️ 配置

超时配置

🛠️ 可用工具

consult_gemini

consult_gemini_with_files

web_search

📋 使用示例

基础代码分析

详细文件审查

多文件分析

网页搜索

大文件保护措施

🏗️ 架构

核心设计

项目结构

🔧 开发

本地测试

与 Claude Code 集成

🔍 故障排除

CLI 不可用

连接问题

常见错误消息

🤝 贡献

快速贡献指南

📄 许可证

🔄 版本历史

🆘 支持

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

`consult_gemini`

`consult_gemini_with_files`

`web_search`