MCP Gemini Grounding

🚀 Gemini AI MCP 服務器

這是一個模型上下文協議（MCP）服務器，藉助 Gemini API 的信息關聯功能，提供由人工智能驅動的網絡搜索和內容總結服務。與傳統搜索工具返回原始搜索結果不同，該服務器利用 Gemini AI 整合信息，並提供帶有引用來源的全面答案。

🚀 快速開始

在配置完成後，google_search 工具將在 Claude Code 中可用。你可以通過向 Claude 提出搜索和總結信息的請求來使用它，例如：

• "搜索有關人工智能的最新新聞"
• "查找量子計算的相關信息"
• "當前網頁開發的趨勢有哪些？"

✨ 主要特性

• 利用 Gemini AI 進行網絡搜索並提供整合後的答案。
• 返回由人工智能生成的總結內容，並附帶適當的引用和來源 URL。
• 支持 OAuth 和 API 密鑰兩種認證方式。
• 與 Claude Code 和其他 MCP 客戶端兼容。

📦 安裝指南

從源代碼構建

git clone https://github.com/ml0-1337/mcp-gemini-grounding.git
cd mcp-gemini-grounding
make build

若要查看所有可用命令的完整列表，請運行：

make help

全局安裝

# 從源代碼安裝
make install

# 或者直接使用 go install
go install github.com/ml0-1337/mcp-gemini-grounding/cmd/gemini-grounding@latest

📚 詳細文檔

配置

認證

服務器支持兩種認證方式：

1. OAuth 憑證（推薦）
   • 自動使用 ~/.gemini/oauth_creds.json 中的憑證。
   • 這些憑證是在你使用 Gemini CLI 進行認證時創建的。
   • 詳細說明請參閱 OAuth2 設置指南。
2. API 密鑰（備用）
   • 設置 GEMINI_API_KEY 環境變量。
   • 從 Google AI Studio 獲取你的 API 密鑰。

Claude Code 配置

根據你的需求選擇合適的配置範圍： 重要提示：在使用以下 CLI 命令時，你必須提供二進制文件的完整絕對路徑（例如，/Users/username/projects/mcp-gemini-grounding/mcp-gemini-grounding）。像 ./mcp-gemini-grounding 這樣的相對路徑會導致服務器啟動失敗。

1. 本地範圍（特定項目，私有）

適用於：個人開發服務器、實驗性配置或包含敏感憑證的服務器。 選項 A：使用 CLI（推薦）

# 如果是全局安裝
claude mcp add gemini-grounding

# 或者使用完整絕對路徑（必需 - 相對路徑會失敗）
claude mcp add gemini-grounding /full/path/to/mcp-gemini-grounding
# 示例：claude mcp add gemini-grounding /Users/username/projects/mcp-gemini-grounding/mcp-gemini-grounding

選項 B：手動配置

1. 在 Claude Code 中打開你的項目。
2. 點擊底部狀態欄中的 MCP 服務器圖標。
3. 選擇 "添加 MCP 服務器..."。
4. 選擇 "gemini" 並進行配置：

{
  "mcpServers": {
    "gemini-grounding": {
      "command": "/path/to/mcp-gemini-grounding",
      "env": {
        "GEMINI_API_KEY": "$GEMINI_API_KEY"
      }
    }
  }
}

此配置存儲在你項目的 .claude/settings.local.json 文件中，不會與他人共享。

2. 項目範圍（團隊共享）

適用於：團隊協作，所有成員需要相同的 MCP 服務器配置。 選項 A：使用 CLI（推薦）

# 如果是全局安裝
claude mcp add gemini-grounding -s project

# 或者使用完整絕對路徑（必需 - 相對路徑會失敗）
claude mcp add gemini-grounding -s project /full/path/to/mcp-gemini
# 示例：claude mcp add gemini-grounding -s project /Users/username/projects/mcp-gemini-grounding/mcp-gemini-grounding

選項 B：手動配置

1. 在項目根目錄下創建一個 .mcp.json 文件。
2. 添加以下配置：

{
  "mcpServers": {
    "gemini-grounding": {
      "command": "mcp-gemini-grounding",
      "env": {
        "GEMINI_API_KEY": "$GEMINI_API_KEY"
      }
    }
  }
}

3. 將此文件提交到版本控制系統。
4. 團隊成員可以在本地設置他們的 GEMINI_API_KEY 環境變量。

注意：永遠不要直接提交實際的 API 密鑰。始終使用環境變量引用（例如，$GEMINI_API_KEY）。

3. 用戶範圍（全局）

適用於：你希望在所有項目中都能使用的個人實用服務器。 選項 A：使用 CLI（推薦）

# 如果是全局安裝
claude mcp add gemini-grounding -s user

# 或者使用完整絕對路徑（必需 - 相對路徑會失敗）
claude mcp add gemini-grounding -s user /full/path/to/mcp-gemini
# 示例：claude mcp add gemini-grounding -s user /Users/username/projects/mcp-gemini-grounding/mcp-gemini-grounding

選項 B：手動配置

1. 打開 Claude Code 設置。
2. 導航到 MCP 服務器配置頁面。
3. 將 gemini 服務器添加到你的用戶設置中：

{
  "mcpServers": {
    "gemini-grounding": {
      "command": "gemini",
      "env": {
        "GEMINI_API_KEY": "$GEMINI_API_KEY"
      }
    }
  }
}

如果你使用 go install 進行了全局安裝，你可以直接使用 "command": "gemini"。

設置環境變量

添加服務器後，設置你的 API 密鑰：

# macOS/Linux
export GEMINI_API_KEY="your-api-key-here"

# Windows (PowerShell)
$env:GEMINI_API_KEY="your-api-key-here"

# Windows (Command Prompt)
set GEMINI_API_KEY=your-api-key-here

若要進行永久配置，請將導出語句添加到你的 shell 配置文件（~/.bashrc、~/.zshrc 等）中。

配置優先級

Claude Code 按以下順序應用配置（優先級從高到低）：

1. 本地範圍 - 特定項目的設置優先於其他所有設置。
2. 項目範圍 - 團隊共享的設置。
3. 用戶範圍 - 全局個人設置。 這允許在需要時使用個人配置覆蓋共享配置。

安全最佳實踐

1. API 密鑰管理：
   • 永遠不要直接在配置文件中提交 API 密鑰。
   • 使用環境變量：$GEMINI_API_KEY。
   • 在你的 shell 配置文件中設置環境變量：

export GEMINI_API_KEY="your-api-key-here"

2. OAuth 憑證：
   • 如果可用，服務器會自動使用 ~/.gemini/oauth_creds.json 中的 OAuth 憑證。
   • 無需對 OAuth 進行配置 - 它會自動檢測。
3. 團隊環境：
   • 使用項目範圍（.mcp.json），且不包含敏感數據。
   • 每個團隊成員在本地設置自己的 API 密鑰。
   • 考慮使用 OAuth 以提高安全性。

工具架構

{
  "name": "google_search",
  "description": "通過 Gemini AI 的信息關聯功能使用 Google 搜索來查找信息，並提供帶有引用的整合答案。返回由人工智能生成的總結內容，而不是原始搜索結果。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "在網絡上查找信息的搜索查詢"
      }
    },
    "required": ["query"]
  }
}

輸出格式

該工具返回的搜索結果包含：

• 帶有內聯引用的主要內容（例如，[1]、[2]）。
• 包含標題和 URL 的來源列表。
• 易於閱讀的格式。

示例輸出：

關於 "量子計算" 的網絡搜索結果：

量子計算是一個快速發展的領域[1]。最近的突破顯示了其在實際應用中的潛力[2]。

來源：
[1] 量子計算解釋 - MIT (https://mit.edu/quantum)
[2] 最新量子突破 - Nature (https://nature.com/quantum)

開發

快速開始

# 安裝依賴
make deps

# 構建項目
make build

# 運行測試
make test

# 運行所有質量檢查
make audit

可用的 Make 命令

運行 make help 查看所有可用命令。主要命令包括：

• 構建與運行：make build、make run、make install
• 測試：make test、make cover、make test-race
• 質量檢查：make fmt、make vet、make lint、make audit
• 開發：make dev、make watch（需要 air）
• 跨平臺：make build-all（為 Linux、macOS、Windows 構建）
• MCP 集成：make mcp-install、make mcp-config
• 發佈：make release、make checksum

運行測試

# 運行所有測試
make test

# 運行帶覆蓋率的測試
make cover

# 運行帶競態檢測的測試
make test-race

# 生成 HTML 覆蓋率報告
make cover-html

測試腳本

scripts/test/ 目錄中提供了各種用於 OAuth2 和 API 測試的腳本。詳細信息請參閱 scripts/test/README.md。

架構

graph TD
    subgraph User
        A[MCP Client e.g. Claude Code]
    end

    subgraph "mcp-gemini-grounding"
        B[cmd/gemini-grounding/main.go]
        C[internal/search]
        D[internal/gemini]
        E[internal/auth]
    end

    subgraph "Google Cloud"
        F[Gemini API]
    end

    A -- MCP Request --> B
    B -- Initializes --> C
    B -- Initializes --> D
    B -- Initializes --> E
    C -- Uses --> D
    D -- Uses --> E
    D -- Makes API Calls --> F

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style F fill:#bbf,stroke:#333,stroke-width:2px

項目結構

mcp-gemini-grounding/
├── cmd/gemini-grounding/ # 主應用程序入口點
├── internal/
│   ├── auth/           # 認證處理
│   ├── gemini/         # Gemini API 客戶端
│   └── search/         # MCP 工具處理程序
├── go.mod
├── go.sum
└── README.md

故障排除

認證錯誤

1. 檢查 OAuth 憑證是否存在：

ls ~/.gemini/oauth_creds.json

2. 或者確保已設置 API 密鑰：

echo $GEMINI_API_KEY

連接問題

• 確保你有網絡連接。
• 檢查 Gemini API 在你所在地區是否可用。
• 驗證你的 API 密鑰或 OAuth 憑證是否有效。

無結果

• 嘗試不同的搜索查詢。
• 檢查 Gemini API 的狀態。
• 確保你沒有超出速率限制。

📄 許可證

本項目採用 MIT 許可證 - 詳細信息請參閱 LICENSE 文件。

貢獻

歡迎貢獻代碼！請隨時提交拉取請求。

倉庫

https://github.com/ml0-1337/mcp-gemini-grounding

演示