mcp-vertexai-search

在构建基于大语言模型的应用时，一个常见的挑战是如何让模型访问你的私有数据，同时避免产生“幻觉”。Google Cloud 的 Vertex AI Search 提供了强大的企业搜索能力，而 Gemini 模型则可以通过 Grounding（ grounding ）技术，基于你的私有数据生成更可靠的答案。

但是，如何让 AI 助手（如 Claude ）方便地调用 Vertex AI Search 的能力呢？这就是 mcp-vertexai-search 要解决的问题。它是一个 MCP 服务器，作为 AI 客户端与 Vertex AI Search 之间的桥梁，让你可以通过标准化的 MCP 协议，用自然语言搜索你的私有数据存储库。

项目基本信息

一、项目介绍

mcp-vertexai-search 是一个用 Python 编写的 MCP 服务器，它利用 Vertex AI 的 Grounding 技术，为 AI 模型提供搜索私有数据的能力。简单来说，它允许你配置一个或多个 Vertex AI Datastore（数据存储），然后通过 MCP 协议，让 AI 助手能够查询这些数据存储中的信息，并基于搜索结果来回答用户的问题。

这个项目的核心是 Grounding。当用户提问时，服务器会先去 Vertex AI Datastore 中搜索相关文档，然后将这些文档作为上下文提供给 Gemini 模型，让模型基于这些真实数据生成答案，从而极大减少幻觉。

该服务器支持 stdio 和 SSE 两种传输方式，并提供了 Dockerfile 用于容器化部署。它最适合已经使用 Google Cloud 生态、并且希望将私有数据搜索能力集成到 AI 工作流中的团队。

二、核心优势

基于 Vertex AI 的企业级搜索
直接利用 Google Cloud 的 Vertex AI Search 和 Grounding 技术，享受其高可用性、安全性和扩展能力。搜索结果更精准，尤其是针对企业内部的复杂文档。

支持多个数据存储
你可以配置多个 Vertex AI Datastore，每个数据存储可以对应一个工具。AI 可以根据用户的问题，选择合适的数据存储进行搜索。

灵活的配置管理
通过 YAML 配置文件，你可以精细控制 Gemini 模型的参数（如 temperature 、top_p 等），以及每个数据存储的 project_id 、location 和 datastore_id 。

支持服务账号模拟
在生产环境中，你可以配置 impersonate_service_account 来模拟一个服务账号，从而获得精细的权限控制，而无需直接使用高权限账号。

两种传输方式
支持 stdio（标准输入输出，适合本地集成）和 SSE（ Server-Sent Events ，适合远程服务），方便集成到各种 MCP 客户端中。

三、适用场景

企业内部知识库搜索
将公司的内部 Wiki 、技术文档、 HR 手册等导入 Vertex AI Datastore。员工可以通过 AI 助手直接提问，例如：“我们的年假申请流程是什么？” AI 会基于最新的公司文档回答。

客户支持文档检索
将产品手册、常见问题解答等导入数据存储。客服人员可以快速询问：“关于 X 功能的最新说明是什么？” 或者“如何解决 Y 错误？”

开发团队的 API 文档查询
将内部 API 文档或 SDK 指南导入 Vertex AI 。开发者可以在代码编辑器中直接询问：“如何调用用户授权接口？” AI 会基于文档生成代码示例。

联网辅助的事实核查
虽然主要用于私有数据，但结合 Vertex AI 的 public data grounding 能力，也可以用于让 AI 在回答时引用权威的公开信息来源。

研究与合规审查
将合规文档、法律法规等导入数据存储。审查人员可以问：“关于数据保留政策的最新要求是什么？” AI 会精确指出相关条款。

四、安装教程

安装 mcp-vertexai-search 需要你拥有一个 Google Cloud 项目，并已创建 Vertex AI Datastore （数据存储）。项目使用 uv 作为包管理器和运行工具。

第一步：克隆代码

git clone git@github.com:ubie-oss/mcp-vertexai-search.git
cd mcp-vertexai-search

第二步：创建虚拟环境并安装依赖

uv venv
uv sync --all-extras

第三步：准备配置文件

复制配置模板并编辑：

cp config.yml.template config.yml

编辑 config.yml ，至少需要填写以下部分：

• model 部分：你的 Vertex AI 项目 ID、位置（如 us-central1）、模型名称（如 gemini-1.5-pro）。
• data_stores 部分：你的数据存储的项目 ID、位置（注意：数据存储的位置通常是 us 或 eu 这样的双字母代码）、数据存储 ID，以及一个对该数据存储的描述。

一个简化的 config.yml 示例如下：

server:
  name: "my-vertexai-search"

model:
  model_name: "gemini-1.5-pro"
  project_id: "your-gcp-project-id"
  location: "us-central1"
  generate_content_config:
    temperature: 0.2

data_stores:
  - project_id: "your-gcp-project-id"
    location: "us"
    datastore_id: "your-datastore-id"
    tool_name: "search_company_docs"
    description: "搜索公司内部文档，包括 HR政策、技术指南等。"

第四步：测试搜索功能（可选）

在配置 MCP 服务器之前，你可以先测试数据存储的连通性和搜索效果：

uv run mcp-vertexai-search search --config config.yml --query "年假政策"

如果配置正确，你会看到基于你数据存储的搜索结果。

第五步：启动 MCP 服务器

使用 stdio 模式（适合 Claude Desktop 等本地客户端）：

uv run mcp-vertexai-search serve --config config.yml --transport stdio

使用 SSE 模式（适合远程部署）：

uv run mcp-vertexai-search serve --config config.yml --transport sse --host 0.0.0.0 --port 8080

第六步：配置 MCP 客户端

对于 Claude Desktop，编辑配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json；Windows: %AppData%\Claude\claude_desktop_config.json），添加以下内容，注意使用绝对路径。

{
  "mcpServers": {
    "vertexai-search": {
      "command": "uv",
      "args": [
        "--directory", "/你的完整路径/mcp-vertexai-search",
        "run",
        "mcp-vertexai-search",
        "serve",
        "--config", "/你的完整路径/mcp-vertexai-search/config.yml",
        "--transport", "stdio"
      ]
    }
  }
}

重启 Claude Desktop 即可使用。

五、使用示例

假设你已经正确配置，并且数据存储中包含了公司的人力资源文档。以下是在 Claude Desktop 中可能的对话。

示例1：基本政策查询

用户输入：我们公司的带薪年假有多少天？

Claude 会调用配置中对应的工具（如 search_company_docs），搜索数据存储，然后基于返回的文档回答：“根据公司 HR 手册第 3.2 节，服务满一年的员工每年享有 15 个工作日的带薪年假。”

示例2：多步查询与追问

用户输入：技术团队使用的代码审查流程是什么？

Claude 会搜索相关文档并回答。你可以接着问：那这个流程中，谁有最终合并代码的权限？ Claude 会基于同一次搜索的上下文或再次搜索来回答。

示例3：跨数据存储查询

假设你配置了两个数据存储，一个用于“HR 文档”，另一个用于“技术文档”。你可以问：

用户输入：在 HR 文档中查找病假政策，同时在技术文档中查找 CI/CD 最佳实践。

不过，目前的工具设计可能一次只针对一个数据存储。你可以将问题拆解，或者让 AI 依次调用两个工具。

六、常见问题

问题1：启动服务器时提示“找不到模块 ‘google-cloud-discoveryengine’”之类。

解决方案：确保你已经正确执行了 uv sync --all-extras ，这会安装所有需要的依赖。如果仍然报错，可以手动安装： uv pip install google-cloud-discoveryengine google-cloud-aiplatform。

问题2：认证失败，提示无法访问 Vertex AI API。

解决方案：确保你的环境中已配置了 Google Cloud 的认证。常见方式：

• 运行 gcloud auth application-default login 进行本地开发测试。
• 在生产环境，使用服务账号密钥（设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量）或配置 impersonate_service_account。

问题3：数据存储的位置（location）应该如何填写？

解决方案：注意区分 model.location 和 data_stores.location。

• model.location 是 Vertex AI 模型的位置，通常是一个具体的区域，如 us-central1、europe-west4 。
• data_stores.location 是数据存储的位置，如果是全局的数据存储，通常是 us 或 eu 这样的双字母代码。请参考 Google Cloud 文档确认你的数据存储位置。

问题4：搜索没有返回任何结果，但我确定数据存储中有数据。

解决方案：首先使用 mcp-vertexai-search search 命令直接测试，看是否有输出。如果没有，检查查询词是否与文档中的内容匹配。Vertex AI Search 的索引可能需要一些时间（尤其是新导入的数据）。另外，检查配置文件中的 project_id 和 datastore_id 是否正确。

问题5：这个服务器是否支持流式响应？

解决方案：该项目目前似乎不支持流式响应（ streaming ），即它会等待完整的搜索结果后再返回。对于长时间的搜索，用户可能会感觉稍有延迟。

七、总结

mcp-vertexai-search 是一个专业且实用的 MCP 服务器，它完美地结合了 Google Cloud Vertex AI 的企业级搜索能力和 MCP 协议的开放标准。对于已经使用或计划使用 Google Cloud 的企业来说，这是一个将私有数据安全地、可控地接入 AI 工作流的优秀解决方案。

该项目的亮点在于：

• 专业性：充分利用了 Vertex AI Grounding 技术，而不是简单地调用通用搜索 API。
• 灵活性：支持多数据存储、服务账号模拟和两种传输协议。
• 企业级：提供了 Dockerfile 、配置模板和详细的测试命令，便于集成到现有 CI/CD 流程中。

35 颗星虽然看似不多，但这可能反映其面向的是较专业的 GCP 用户群体。如果你是其中之一，这个项目值得你投入时间研究。通过它，你可以将散布在各个数据孤岛中的企业知识，以对话的方式交付给每一位员工。