Gemini Bridge

🚀 Gemini Bridge

Gemini Bridge 是一个轻量级的 MCP（模型上下文协议）服务器，它借助官方 CLI 让 AI 编码助手与谷歌的 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 编码助手配合使用。

🚀 快速开始

前提条件

1. 安装 Gemini CLI：

   npm install -g @google/gemini-cli
   

2. 使用 Gemini 进行身份验证：

   gemini auth login
   

3. 验证安装：

   gemini --version
   

安装

🎯 推荐：通过 PyPI 安装

# 从 PyPI 安装
pip install gemini-bridge

# 使用 uvx 添加到 Claude Code（推荐）
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

可选：从源代码安装

# 克隆仓库
git clone https://github.com/shelakh/gemini-bridge.git
cd gemini-bridge

# 构建并在本地安装
uvx --from build pyproject-build
pip install dist/*.whl

# 添加到 Claude Code
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

开发环境安装

# 克隆并以开发模式安装
git clone https://github.com/shelakh/gemini-bridge.git
cd gemini-bridge
pip install -e .

# 添加到 Claude Code（开发模式）
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 的客户端 ✅

配置示例

# 推荐安装方式
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

# 开发环境安装
claude mcp add gemini-bridge-dev -s user -- python -m src

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

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

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

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

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

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

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

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

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

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

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

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

通用用法

一旦与任何客户端完成配置，即可使用以下两个相同的工具：

1. 提出常规问题：例如“此代码库中使用了哪些身份验证模式？”
2. 分析特定文件：例如“审查这些身份验证文件，查找安全问题”

服务器的实现是相同的，仅客户端配置有所不同！

⚙️ 配置

超时配置

默认情况下，Gemini Bridge 对所有 CLI 操作使用 60 秒的超时时间。对于较长的查询（大文件、复杂分析），你可以使用 GEMINI_BRIDGE_TIMEOUT 环境变量配置自定义超时时间。

配置示例：

# 添加自定义超时时间（120 秒）
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 秒（若未配置）
• 范围：任何正整数（秒）
• 推荐值：大文件分析时推荐 120 - 300 秒
• 无效值：将回退到 60 秒并给出警告

💻 使用示例

基础用法

# 简单的研究查询
consult_gemini(
    query="What authentication patterns are used in this project?",
    directory="/Users/dev/my-project"
)

高级用法

详细文件审查

# 分析特定文件
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"
)

多文件分析

# 比较多个实现文件
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"]
)

🏗️ 架构

核心设计

• 以 CLI 为先：直接通过子进程调用 gemini 命令。
• 无状态：每个工具调用都是独立的，无需会话状态。
• 固定超时：最大执行时间为 60 秒。
• 简单的错误处理：采用快速失败策略，提供清晰的错误信息。

项目结构

gemini-bridge/
├── src/
│   ├── __init__.py              # 入口点
│   ├── __main__.py              # 模块执行入口点
│   └── mcp_server.py            # 主要 MCP 服务器实现
├── .github/                     # GitHub 模板和工作流
├── pyproject.toml              # Python 包配置
├── README.md                   # 本文件
├── CONTRIBUTING.md             # 贡献指南
├── CODE_OF_CONDUCT.md          # 社区标准
├── SECURITY.md                 # 安全策略
├── CHANGELOG.md               # 版本历史
└── LICENSE                    # MIT 许可证

🔧 开发

本地测试

# 以开发模式安装
pip install -e .

# 直接运行
python -m src

# 测试 CLI 可用性
gemini --version

与 Claude Code 集成

通过 MCP 协议正确配置后，服务器会自动与 Claude Code 集成。

🔍 故障排除

CLI 不可用

# 安装 Gemini CLI
npm install -g @google/gemini-cli

# 进行身份验证
gemini auth login

# 测试
gemini --version

连接问题

• 验证 Gemini CLI 是否已正确进行身份验证。
• 检查网络连接。
• 确保 Claude Code MCP 配置正确。
• 检查 gemini 命令是否在你的 PATH 中。

常见错误信息

• “CLI not available”：Gemini CLI 未安装或不在 PATH 中。
• “Authentication required”：运行 gemini auth login 进行身份验证。
• “Timeout after 60 seconds”：查询耗时过长，尝试将其拆分为更小的部分。

🤝 贡献

我们欢迎社区的贡献！请阅读我们的 贡献指南 以了解如何开始。

快速贡献指南

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 如有必要，添加测试
5. 提交拉取请求

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🔄 版本历史

详细的版本历史请参阅 CHANGELOG.md。

🆘 支持

• 问题反馈：通过 GitHub Issues 报告错误或请求功能。
• 讨论交流：加入社区讨论。
• 文档：可在 docs/ 目录中创建额外的文档。

重点：通过官方 CLI 在 Claude Code 和 Gemini AI 之间搭建一个简单可靠的桥梁。