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 之間搭建一個簡單可靠的橋樑。