项目介绍
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编码助手
🚀 快速开始
预备条件
-
安装Gemini CLI：
npm install -g @google/gemini-cli -
与Gemini认证：
gemini auth login -
验证安装：
gemini --version
安装
🎯 推荐：PyPI安装
# 从PyPI安装
pip install gemini-bridge
# 添加到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的客户端 ✅
配置示例
<details> <summary><strong>Claude Code</strong>（默认）</summary># 推荐安装
claude mcp add gemini-bridge -s user -- uvx gemini-bridge
# 开发安装
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": {}
}
}
}
前往：设置 → Cursor 设置 → MCP → 添加新的全局MCP服务器
配置（工作区中的.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服务器
- 选择已安装标签页 → 高级MCP设置
- 在
cline_mcp_settings.json中添加：
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}
前往：设置 → MCP → 添加MCP服务器
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}
- 导航至设置 → MCP服务器 → 添加服务器
- 填写服务器详情：
- 名称：
gemini-bridge - 类型：
STDIO - 命令：
uvx - 参数：
["gemini-bridge"]
- 名称：
- 保存配置
使用UI：
- 点击汉堡菜单 → 设置 → 工具
- 点击**+ 添加MCP**按钮
- 输入命令：
uvx gemini-bridge - 名称：Gemini Bridge
手动配置：
"augment.advanced": {
"mcpServers": [
{
"name": "gemini-bridge",
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
]
}
- 转到设置 → MCP服务器 → 编辑全局配置
- 在
mcp_settings.json中添加：
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}
- 转到Zencoder菜单（...） → 工具 → 添加自定义MCP
- 添加配置：
{
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
- 点击安装按钮
基于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配置自定义超时。
示例配置：
<details> <summary><strong>Claude Code</strong></summary># 添加自定义超时（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
直接CLI桥接用于简单查询。
参数：
query（字符串）：发送给Gemini的问题或提示directory（字符串）：查询的工作目录（默认：当前目录）model（字符串，可选）：使用的模型 - "flash" 或 "pro"（默认："flash"）
示例：
consult_gemini(
query="查找此代码库中的认证模式",
directory="/path/to/project",
model="flash"
)
consult_gemini_with_files
带有文件附件的CLI桥接，用于详细分析。
参数：
query（字符串）：发送给Gemini的问题或提示directory（字符串）：查询的工作目录files（列表）：相对于目录的文件路径列表model（字符串，可选）：使用的模型 - "flash" 或 "pro"（默认："flash"）
示例：
consult_gemini_with_files(
query="分析这些认证文件并提出改进建议",
directory="/path/to/project",
files=["src/auth.py", "src/models.py"],
model="pro"
)
📋 使用示例
基本代码分析
# 简单的研究查询
consult_gemini(
query="在这个项目中使用了哪些认证模式？",
directory="/Users/dev/my-project"
)
详细文件审查
# 分析特定文件
consult_gemini_with_files(
query="审查这些文件并提出安全改进意见",
directory="/Users/dev/my-project",
files=["src/auth.py", "src/middleware.py"],
model="pro"
)
多文件分析
# 比较多个实现文件
consult_gemini_with_files(
query="比较这些数据库实现并推荐最佳方法",
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不可用"：Gemini CLI未安装或不在PATH中
- "需要认证"：运行
gemini auth login - "超时60秒"：查询耗时过长，尝试将其拆分为更小的部分
🤝 贡献
我们欢迎社区贡献！请阅读我们的贡献指南，了解如何开始。
快速贡献指南
- 分叉仓库
- 创建功能分支
- 进行更改
- 如适用，添加测试
- 提交拉取请求
📄 许可证
该项目采用MIT许可证——详情参见LICENSE文件。
🔄 版本历史
详见CHANGELOG.md获取详细的版本历史。
🆘 支持
- 问题：通过GitHub Issues报告错误或请求功能
- 讨论：加入社区讨论
- 文档：可以在
docs/目录中创建额外文档
重点：一个简单、可靠的桥梁，通过官方CLI连接Claude Code和Gemini AI。