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

演示