Gemini Bridge

双子座大桥

一个轻量级的MCP（模型上下文协议）服务器，使AI编码助手能够通过官方CLI与谷歌的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+）

🚀 快速开始

先决条件

1. 安装Gemini CLI:

   npm install -g @google/gemini-cli

1. 通过Gemini进行身份验证:

   gemini auth login

1. 验证安装:

   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客户端

• 克劳德代码 ✅ （默认）
• 光标 ✅
• VS Code ✅
• 帆板运动 ✅
• 克莱恩 ✅
• 虚空 ✅
• 樱桃工作室 ✅
• 增强 ✅
• Roo代码 ✅
• Zencoder ✅
• 任何兼容MCP的客户端 ✅

配置示例

Claude Code (Default)

# 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

全局配置 (~/.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

VS Code

配置 (.vscode/mcp.json 在您的工作空间中）：

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

替代方案：通过扩展

1. 打开扩展视图（Ctrl+Shift+X）
2. 搜索MCP扩展
3. 使用以下命令添加自定义服务器： uvx gemini-bridge

Windsurf

添加到您的Windsurf MCP配置中：

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

Cline (VS Code Extension)

1. 打开Cline并单击 MCP服务器 在顶部导航中
2. 选择 已安装 tab → 高级MCP设置
3. 添加 cline_mcp_settings.json:

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

Void

首选 Settings → MCP → Add MCP Server

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

Cherry Studio

1. 导航至 设置→ MCP服务器→ 添加服务器
2. 填写服务器详细信息：

- 名字: gemini-bridge - 类型: STDIO - 命令: uvx - 参数: ["gemini-bridge"]

1. 保存配置

Augment

使用UI：

1. 点击汉堡菜单→ 设置 → 工具
2. 点击 +添加MCP 按钮
3. 输入命令： uvx gemini-bridge
4. 姓名： 双子座大桥

手动配置：

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

Roo Code

1. 首选 设置→ MCP服务器→ 编辑全局配置
2. 添加 mcp_settings.json:

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

Zencoder

1. 转到Zencoder菜单（…）→ 工具 → 添加自定义MCP
2. 添加配置：

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

1. 点击 安装 按钮

Alternative Installation Methods

对于基于pip的安装：

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

对于开发/本地测试：

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

用于npm风格的安装 （如果需要）：

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

普遍使用

一旦配置了任何客户端，请使用相同的两个工具：

1. 提出一般性问题：“此代码库中使用了哪些身份验证模式？”
2. 分析特定文件：“检查这些身份验证文件是否存在安全问题”

服务器实现完全相同 -只有客户端配置不同！

⚙️ 配置

超时配置

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

示例配置：

Claude Code

# Add with custom timeout (120 seconds)
claude mcp add gemini-bridge -s user --env GEMINI_BRIDGE_TIMEOUT=120 -- uvx gemini-bridge

Manual Configuration (mcp_settings.json)

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

超时选项：

• 默认：60秒（如果未配置）
• 范围：任何正整数（秒）
• 每次呼叫覆盖：供应 timeout_seconds 使用任一工具进行一次性扩展
• 推荐：120-300秒用于大文件分析
• 无效值：回退到60秒并发出警告

🛠️ 可用工具

consult_gemini

用于简单查询的直接CLI桥。

参数：

• query （string）：发送给双子座的问题或提示
• directory （string）：查询的工作目录
• model （字符串，可选）：要使用的型号-“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）：发送给双子座的问题或提示
• directory （string）：查询的工作目录
• files （list）：相对于目录的文件路径列表
• model （字符串，可选）：要使用的型号-“flash”、“pro”、“flash lite”、“2.5-lite”、“3-pro”、”3-flash”、”3.1-pro”、“3.1-flash-lite”或“auto”（默认值：“flash”）
• timeout_seconds （int，可选）：覆盖此请求的执行超时
• mode （字符串，可选）：要么 "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 （字符串，可选）：要使用的型号-“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秒，但每个请求或通过env var可重写
• 附件护栏：内联模式强制执行轻量级限制； @ 模式委托给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是否经过正确身份验证
• 检查网络连接
• 确保克劳德代码MCP配置正确
• 检查一下 gemini 命令在您的PATH中

常见错误消息

• “CLI不可用”：Gemini CLI未安装或不在PATH中
• “需要身份验证”：运行 gemini auth login
• “60秒后超时”：查询时间过长，请尝试将其分解为更小的部分

🤝 贡献

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

快速贡献指南

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🔄 版本历史

看 更改日志.md 查看详细的版本历史。

🆘 支持

• 问题：通过以下方式报告错误或请求功能
• 讨论：加入社区讨论
• 文档：可以在中创建其他文档 docs/ 目录

______________________________________________________________________

聚焦：通过官方CLI在Claude Code和Gemini AI之间建立简单可靠的桥梁。