适用于数据库的 MCP 工具箱：使 BigQuery 数据集可供 MCP 客户端使用

MCP Toolbox for Databases：向 MCP 客户端提供 BigQuery 数据集

剩余时间：90 分钟

MCP Toolbox for Databases：向 MCP 客户端提供 BigQuery 数据集

关于此 Codelab

上次更新时间：6月 20, 2025

Romin Irani 编写

此页面由 Cloud Translation API 翻译。

1. 简介

在此 Codelab 中，您将使用 MCP 数据库工具箱来提供 BigQuery 数据集。

在本 Codelab 中，您将采用分步方法，具体步骤如下：

从 BigQuery 公共数据集计划中识别特定 BigQuery 数据集（“Google Cloud 版本说明”）。
设置适用于数据库的 MCP Toolbox，以连接到 BigQuery 数据集。
使用智能体开发套件 (ADK) 开发一个智能体，该智能体将利用 MCP Toolbox 来回答用户关于 Google Cloud 版本说明的问题

实践内容

设置 MCP Toolbox for Databases，以便将 Google Cloud 版本说明（一个公开的 BigQuery 数据集）作为 MCP 接口公开给其他 MCP 客户端（IDE、工具等）。

学习内容

探索 BigQuery 公共数据集，然后选择一个特定的数据集。
为我们要向 MCP 客户端提供的 BigQuery 公共数据集设置 MCP 数据库工具箱。
使用智能体开发套件 (ADK) 设计和开发智能体，以回答用户查询。
在本地环境中测试智能体和 MCP Toolbox for Databases。

所需条件

Chrome 网络浏览器。
本地 Python 开发环境。

2. 准备工作

创建项目

在 Google Cloud Console 的项目选择器页面上，选择或创建一个 Google Cloud 项目。
确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。
您将使用 Cloud Shell，它是一个在 Google Cloud 中运行的命令行环境，它预加载了 bq。点击 Google Cloud 控制台顶部的“激活 Cloud Shell”。

“激活 Cloud Shell”按钮图片

连接到 Cloud Shell 后，您可以使用以下命令检查自己是否已通过身份验证，以及项目是否已设置为您的项目 ID：

gcloud auth list

在 Cloud Shell 中运行以下命令，以确认 gcloud 命令了解您的项目。

gcloud config list project

如果项目未设置，请使用以下命令进行设置：

gcloud config set project <YOUR_PROJECT_ID>

如需了解 gcloud 命令和用法，请参阅文档。

3. Google 版本说明数据集和 MCP 客户端

首先，我们来看看 Google Cloud 官方版本说明网页上定期更新的 Google Cloud 版本说明，如下图所示：

您可以订阅该 Feed 网址，但如果我们直接在客服聊天中询问这些版本说明，会怎么样？可以是简单的询问，例如“请告诉我 Google Cloud 版本说明的最新动态”。

4. MCP Toolbox for Databases

MCP Toolbox for Databases 是一个适用于数据库的开源 MCP 服务器，在设计时就考虑到了企业级和生产级质量。它可以处理连接池、身份验证等复杂问题，让您能够更轻松、更快速、更安全地开发工具。

该工具包可帮助您构建生成式 AI 工具，让智能体能够访问数据库中的数据。Toolbox 提供以下功能：

简化开发流程：只需不到 10 行代码即可将工具集成到代理中，在多个代理或框架之间重复使用工具，并更轻松地部署工具的新版本。
性能更出色：连接池、身份验证等最佳实践。
增强型安全性：集成身份验证，更安全地访问您的数据
端到端可观测性：开箱即用的指标和跟踪功能，内置对 OpenTelemetry 的支持。
借助 Toolbox，您可以轻松将数据库连接到任何支持 MCP 的 AI 助理，即使是 IDE 中的 AI 助理也是如此。

Toolbox 位于应用的编排框架和数据库之间，提供用于修改、分发或调用工具的控制平面。它为您提供了一个集中的位置来存储和更新工具，从而简化了工具管理。您可以在代理和应用之间共享工具，并更新这些工具，而无需重新部署应用。

简单来说：

MCP Toolbox 可作为二进制文件、容器映像提供，您也可以从源代码构建它。
它会公开一组您通过 tools.yaml 文件配置的工具。这些工具可视为连接到您的数据源。您可以查看它支持的各种数据源：AlloyDB、BigQuery 等。
由于此工具箱现在支持 MCP，因此您会自动获得一个 MCP 服务器端点，该端点可供代理 (IDE) 使用，您也可以在使用各种框架（例如智能体开发套件 [ADK]）开发智能体应用时使用该端点。

本文将重点介绍以下方面：

总而言之，我们将在 MCP Toolbox for Databases 中创建一个配置，该配置知道如何连接到我们的 BigQuery 数据集。然后，我们将使用智能体开发套件 (ADK) 开发一个智能体，该智能体将与 MCP Toolbox 端点集成，并允许我们发送自然查询来询问数据集。不妨将其视为您正在开发的代理应用，该应用知道如何与 BigQuery 数据集进行通信，并运行一些查询。

5. Google Cloud 版本说明的 BigQuery 数据集

Google Cloud 公共数据集计划是一项计划，旨在为您的应用提供一系列数据集。Google Cloud 版本说明数据库就是其中一个数据集。此数据集提供的信息与 Google Cloud 官方版本说明网页中的信息相同，并且可作为可公开查询的数据集使用。

为了进行测试，我只需运行下面的简单查询即可验证数据集：

SELECT
       product_name,description,published_at
     FROM
       `bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
     WHERE
       DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
     GROUP BY product_name,description,published_at
     ORDER BY published_at DESC

这样，我就可以从“版本说明”数据集中获取过去 7 天内发布的记录列表。

将其替换为您选择的任何其他数据集以及您需要的相应查询和参数。现在，我们只需在 MCP Toolbox for Databases 中将其设置为数据源和工具即可。我们来看看具体该怎么做。

6. 安装 MCP Toolbox for Databases

在本地机器上打开一个终端，然后创建一个名为 mcp-toolbox 的文件夹。

mkdir mcp-toolbox

通过以下命令前往 mcp-toolbox 文件夹：

cd mcp-toolbox

通过以下脚本安装二进制版本的 MCP Toolbox for Databases。以下命令适用于 Linux，但如果您使用的是 Mac 或 Windows，请确保下载正确的二进制文件。请访问适用于您的操作系统和架构的版本页面，然后下载正确的二进制文件。

export VERSION=0.7.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

现在，我们已经有了可供使用的二进制版工具箱。下一步是使用数据源和其他配置配置该工具箱。

7. 配置 MCP Toolbox for Databases

现在，我们需要在 MCP 数据库工具箱所需的 tools.yaml 文件中定义 BigQuery 数据集和工具。tools.yaml 文件是配置 Toolbox 的主要方式。

在同一文件夹（即 mcp-toolbox）中创建一个名为 tools.yaml 的文件，其内容如下所示。

您可以使用 Cloud Shell 中提供的 nano 编辑器。nano 命令如下所示：“nano tools.yaml”。

请务必将 YOUR_PROJECT_ID 值替换为您的 Google Cloud 项目 ID。

sources:
 my-bq-source:
   kind: bigquery
   project: YOUR_PROJECT_ID

tools:
 search_release_notes_bq:
   kind: bigquery-sql
   source: my-bq-source
   statement: |
    SELECT
     product_name,description,published_at
    FROM
      `bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
    WHERE
     DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
    GROUP BY product_name,description,published_at
    ORDER BY published_at DESC
   description: |
    Use this tool to get information on Google Cloud Release Notes.

toolsets:
 my_bq_toolset:
   - search_release_notes_bq

我们先简要了解一下该文件：

来源代表工具可以与之互动的不同数据源。来源表示工具可以与之交互的数据源。您可以在 tools.yaml 文件的 sources 部分将 Sources 定义为映射。通常，来源配置将包含与数据库建立连接和交互所需的所有信息。在本例中，我们定义了一个 BigQuery 来源 my-bq-source，您需要提供自己的 Google Cloud 项目 ID。如需了解详情，请参阅来源参考文档。
工具用于定义代理可以执行的操作，例如读取和写入来源。工具代表代理可以执行的操作，例如运行 SQL 语句。您可以在 tools.yaml 文件的 tools 部分将“Tools”定义为映射。通常，工具需要有操作的来源。在本例中，我们定义了一个工具 search_release_notes_bq。这引用了我们在第一步中定义的 BigQuery 来源 my-bq-source。它还包含 AI 客服人员客户端将使用的语句和指令。如需了解详情，请参阅工具参考文档。
最后，我们有工具包，可让您定义要一起加载的一组工具。这对于根据代理或应用定义不同的组非常有用。在本例中，我们有一个工具包定义，其中目前只定义了我们定义的一个现有工具 search_release_notes_bq。您可以有多个工具包，其中包含不同工具的组合。

因此，目前，我们仅定义了一项工具，用于根据查询获取过去 7 天的版本说明。不过，您也可以使用参数进行各种组合。

如需了解更多配置详情（来源、工具），请参阅 MCP Toolbox for Databases 中的 BigQuery 数据源配置。

8. 测试 MCP Toolbox for Databases

我们已下载并使用 mcp-toolbox 文件夹中的 tools.yaml 文件配置了 Toolbox。我们先在本地运行该代码。

执行以下命令：

./toolbox --tools-file="tools.yaml"

成功执行后，您应该会看到服务器启动，并且示例输出类似于以下内容：

2025-06-17T07:48:52.989710733Z INFO "Initialized 1 sources." 
2025-06-17T07:48:52.989805642Z INFO "Initialized 0 authServices." 
2025-06-17T07:48:52.989847035Z INFO "Initialized 1 tools." 
2025-06-17T07:48:52.989889742Z INFO "Initialized 2 toolsets." 
2025-06-17T07:48:52.990357879Z INFO "Server ready to serve!"

MCP Toolbox 服务器默认在端口 5000 上运行。如果您发现端口 5000 已在使用中，请随意使用其他端口（例如 7000），具体请参阅以下命令。在后续命令中，请使用 7000 而非 5000 端口。

./toolbox --tools-file "tools.yaml" --port 7000

我们来使用 Cloud Shell 进行测试。

在 Cloud Shell 中，点击“网页预览”，如下所示：

点击更改端口，将端口设置为 5000（如下所示），然后点击“更改并预览”。

这应该会产生以下输出：

在浏览器网址中，将以下内容添加到网址末尾：

/api/toolset

这应该会调出当前配置的工具。输出示例如下所示：

{
  "serverVersion": "0.7.0+binary.linux.amd64.714d990c34ee990e268fac1aa6b89c4883ae5023",
  "tools": {
    "search_release_notes_bq": {
      "description": "Use this tool to get information on Google Cloud Release Notes.\n",
      "parameters": [],
      "authRequired": []
    }
  }
}

此处介绍了 MCP 数据库工具包，其中介绍了一种使用 Python 验证和测试工具的方法。我们将跳过该部分，直接进入下一部分，在其中使用这些工具来介绍 Agent Development Kit (ADK)。

9. 使用智能体开发套件 (ADK) 编写智能体

安装 Agent Development Kit (ADK)

在 Cloud Shell 中打开一个新的终端标签页，然后创建一个名为 my-agents 的文件夹，如下所示。还要前往 my-agents 文件夹。

mkdir my-agents
cd my-agents

现在，我们将使用 venv 创建一个虚拟 Python 环境，如下所示：

python -m venv .venv

按如下方式激活虚拟环境：

source .venv/bin/activate

安装 ADK 和 MCP Toolbox for Databases 软件包以及 langchain 依赖项，如下所示：

pip install google-adk toolbox-core

现在，您可以按如下方式调用 adk 实用程序。

adk

系统会显示命令列表。

$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...

  Agent Development Kit CLI tools.

Options:
  --help  Show this message and exit.

Commands:
  api_server  Starts a FastAPI server for agents.
  create      Creates a new app in the current folder with prepopulated agent template.
  deploy      Deploys agent to hosted environments.
  eval        Evaluates an agent given the eval sets.
  run         Runs an interactive CLI for a certain agent.
  web         Starts a FastAPI server with Web UI for agents.

创建我们的第一个客服应用

现在，我们将使用 adk 通过 adk create 命令为 Google Cloud 版本说明代理应用创建框架，应用名称为 **(gcp-releasenotes-agent-app)**，如下所示。

adk create gcp-releasenotes-agent-app

请按照相应步骤操作，然后选择以下选项：

用于为根代理选择模型的 Gemini 模型。
为后端选择 Vertex AI。
系统会显示您的默认 Google 项目 ID 和区域。选择默认值本身。

Choose a model for the root agent:
1. gemini-2.0-flash-001
2. Other models (fill later)

Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai

Enter Google Cloud project ID [YOUR_GOOGLE_PROJECT_ID]: 
Enter Google Cloud region [us-central1]: 

Agent created in ../my-agents/gcp-releasenotes-agent-app:
- .env
- __init__.py
- agent.py

查看已为代理创建默认模板和所需文件的文件夹。

首先是 .env 文件。其内容如下所示：

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

这些值表示我们将通过 Vertex AI 使用 Gemini，以及 Google Cloud 项目 ID 和位置的各自值。

然后，我们有 __init__.py 文件，该文件会将该文件夹标记为模块，并包含一个用于从 agent.py 文件导入代理的语句。

from . import agent

最后，我们来看看 agent.py 文件。内容如下所示：

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.0-flash-001',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

这是您可以使用 ADK 编写的最简单的智能体。根据 ADK 文档页面，代理是一个独立的执行单元，旨在自主行动以实现特定目标。代理可以执行任务、与用户互动、使用外部工具以及与其他代理协调。

具体而言，LLMAgent（通常别名为 Agent）利用大语言模型 (LLM) 作为其核心引擎，以理解自然语言、推理、规划、生成回答，并动态决定后续步骤或要使用的工具，非常适合灵活的以语言为中心的任务。如需详细了解 LLM Agent，请点击此处。

至此，我们完成了使用智能体开发套件 (ADK) 生成基本智能体的框架。现在，我们将代理连接到 MCP Toolbox，以便它可以使用该工具来回答用户的查询（在本例中，是 Google Cloud 版本说明）。

10. 将客服人员与工具相关联

我们现在将此客服人员与工具相关联。在 ADK 上下文中，工具代表向 AI 智能体提供的特定功能，使其能够执行操作并与世界互动，而不仅仅是利用其核心文本生成和推理能力。

在本例中，我们将为智能体配备我们在 MCP Toolbox for Databases 中配置的工具。

使用以下代码修改 agent.py 文件。请注意，我们在代码中使用的是默认端口 5000，但如果您使用的是其他端口号，请使用该端口号。

from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient

toolbox = ToolboxSyncClient("http://127.0.0.1:5000")

# Load all the tools
tools = toolbox.load_toolset('my_bq_toolset')

root_agent = Agent(
    name="gcp_releasenotes_agent",
    model="gemini-2.0-flash",
    description=(
        "Agent to answer questions about Google Cloud Release notes."
    ),
    instruction=(
        "You are a helpful agent who can answer user questions about the Google Cloud Release notes. Use the tools to answer the question"
    ),
    tools=tools,
)

现在，我们可以测试该代理，它将从使用 MCP Toolbox for Databases 配置的 BigQuery 数据集中提取真实数据。

具体步骤如下：

在 Cloud Shell 的某个终端中，启动 MCP Toolbox for Databases。您可能已经在本地的 5000 端口上运行了该服务，就像我们之前测试的那样。如果没有，请运行以下命令（从 mcp-toolbox 文件夹中运行）来启动服务器：

./toolbox --tools_file "tools.yaml"

理想情况下，您应该会看到服务器已能够连接到数据源，并已加载工具包和工具的输出。示例输出如下所示：

./toolbox --tools-file "tools.yaml"
2025-06-17T07:48:52.989710733Z INFO "Initialized 1 sources." 
2025-06-17T07:48:52.989805642Z INFO "Initialized 0 authServices." 
2025-06-17T07:48:52.989847035Z INFO "Initialized 1 tools." 
2025-06-17T07:48:52.989889742Z INFO "Initialized 2 toolsets." 
2025-06-17T07:48:52.990357879Z INFO "Server ready to serve!"

MCP 服务器成功启动后，在另一个终端中，通过下方所示的 adk run（位于 my-agents 文件夹中）命令启动 Agent。您也可以使用 adk web 命令。

$ adk run gcp-releasenotes-agent-app/

Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent gcp_releasenotes_agent, type exit to exit.

[user]: get me the google cloud release notes


[gcp_releasenotes_agent]: Here are the Google Cloud Release Notes.

Google SecOps SOAR: Release 6.3.49 is being rolled out to the first phase of regions. This release contains internal and customer bug fixes. Published: 2025-06-14

Compute Engine: Dynamic NICs let you add or remove network interfaces to or from an instance without having to restart or recreate the instance. You can also use Dynamic NICs when you need more network interfaces. The maximum number of vNICs for most machine types in Google Cloud is 10; however, you can configure up to 16 total interfaces by using Dynamic NICs. Published: 2025-06-13

Compute Engine: General purpose C4D machine types, powered by the fifth generation AMD EPYC processors (Turin) and Google Titanium, are generally available. Published: 2025-06-13

Google Agentspace: Google Agentspace Enterprise: App-level feature management. As an Agentspace administrator, you can choose to turn the following features on or off for your end users in the web app: Agents gallery, Prompt gallery, No-code agent, NotebookLM Enterprise. Published: 2025-06-13

Cloud Load Balancing: Cloud Load Balancing supports load balancing to multi-NIC instances that use Dynamic NICs. This capability is in Preview. Published: 2025-06-13

Virtual Private Cloud: Dynamic Network Interfaces (NICs) are available in Preview. Dynamic NICs let you update an instance to add or remove network interfaces without having to restart or recreate the instance. Published: 2025-06-13

Security Command Center: The following Event Threat Detection detectors for Vertex AI have been released to Preview:
- `Persistence: New Geography for AI Service`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Admin Activity`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Data Access`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Admin Activity`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Data Access`
- `Privilege Escalation: Anomalous Impersonation of Service Account for AI Admin Activity`
- `Persistence: New AI API Method`
......
......

请注意，代理会使用我们在 MCP Toolbox for Databases (search_release_notes_bq) 中配置的工具，从 BigQuery 数据集中检索数据并相应地设置响应格式。

11. 恭喜

恭喜，您已成功配置适用于数据库的 MCP Toolbox，并配置了可在 MCP 客户端中访问的 BigQuery 数据集。

参考文档

报告错误