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

1. 简介

在此 Codelab 中，您将利用 MCP Toolbox for Databases 来提供 BigQuery 数据集。

在此 Codelab 中，您将采用以下分步方法：

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

实践内容

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

学习内容

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

所需条件

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

2. 准备工作

创建项目

在 Google Cloud 控制台的项目选择器页面上，选择或创建一个 Google 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>

通过以下命令启用所需的 API。这可能需要几分钟时间，请耐心等待。

gcloud services enable cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudfunctions.googleapis.com \
                       aiplatform.googleapis.com \
                       sqladmin.googleapis.com \
                       compute.googleapis.com

成功执行该命令后，您应该会看到类似于以下内容的消息：

Operation "operations/..." finished successfully.

除了使用 gcloud 命令之外，您还可以通过控制台搜索每个产品或使用此链接来完成此操作。

如果缺少任何 API，您始终可以在实现过程中启用它。

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

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

首先，我们来看看 Google Cloud 版本说明，这些说明会在 Google Cloud 版本说明官方网页上定期更新，该网页的屏幕截图如下所示：

您可能会订阅 Feed 网址，但如果我们可以在智能体聊天中询问这些版本说明，那会怎么样呢？也许只需一个简单的查询，例如“向我提供 Google Cloud 版本说明的最新信息”。

4. MCP Toolbox for Databases

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

Toolbox 可帮助您构建 Gen 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.23.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

我们现在已准备好使用工具箱的二进制版本。下一步是使用我们的数据源和其他配置来配置工具箱。

7. 配置 MCP Toolbox for Databases

现在，我们需要在 tools.yaml 文件中定义 BigQuery 数据集和工具，这是 MCP Toolbox for Databases 所需的文件。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 部分中将来源定义为映射。通常，来源配置将包含连接和与数据库交互所需的任何信息。在本例中，我们定义了一个 BigQuery 来源 my-bq-source ，您需要提供您的 Google Cloud 项目 ID。如需了解详情，请参阅来源参考文档。
工具定义了智能体可以执行的操作，例如读取和写入来源。工具表示智能体可以执行的操作，例如运行 SQL 语句。您可以在 tools.yaml 文件的 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

我们已下载 Toolbox，并使用 mcp-toolbox 文件夹中的 tools.yaml 文件对其进行了配置。让我们先在本地运行它。

执行以下命令：

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

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

2025-12-09T08:27:02.777619+05:30 INFO "Initialized 1 sources: my-bq-source" 
2025-12-09T08:27:02.777695+05:30 INFO "Initialized 0 authServices: " 
2025-12-09T08:27:02.777707+05:30 INFO "Initialized 1 tools: search_release_notes_bq" 
2025-12-09T08:27:02.777716+05:30 INFO "Initialized 2 toolsets: my_bq_toolset, default" 
2025-12-09T08:27:02.777719+05:30 INFO "Initialized 0 prompts: " 
2025-12-09T08:27:02.777723+05:30 INFO "Initialized 1 promptsets: default" 
2025-12-09T08:27:02.77773+05:30 WARN "wildcard (`*`) allows all origin to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-origins` flag to prevent DNS rebinding attacks" 
2025-12-09T08:27:02.777839+05:30 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.22.0+binary.linux.amd64.1a6dfe8d37d0f42fb3fd3f75c50988534dbc1b85",
  "tools": {
    "search_release_notes_bq": {
      "description": "Use this tool to get information on Google Cloud Release Notes.\n",
      "parameters": [],
      "authRequired": []
    }
  }
}

通过 MCP Toolbox for Databases 界面测试工具

Toolbox 提供了一个可视化界面（Toolbox 界面 ），让您可以通过修改参数、管理标头和执行调用来直接与工具交互，所有操作都在一个简单的 Web 界面中完成。

如果您想对此进行测试，可以使用我们之前用于启动 Toolbox 服务器的命令，并添加 --ui 选项。

为此，请关闭您可能正在运行的 MCP Toolbox for Databases 服务器的先前实例，然后输入以下命令：

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

理想情况下，您应该会看到服务器已能够连接到我们的数据源，并且已加载工具集和工具的输出。示例输出如下所示，您会注意到它会提及 Toolbox 界面已启动并运行。

2025-12-09T08:28:07.479989+05:30 INFO "Initialized 1 sources: my-bq-source" 
2025-12-09T08:28:07.480065+05:30 INFO "Initialized 0 authServices: " 
2025-12-09T08:28:07.480079+05:30 INFO "Initialized 1 tools: search_release_notes_bq" 
2025-12-09T08:28:07.480087+05:30 INFO "Initialized 2 toolsets: my_bq_toolset, default" 
2025-12-09T08:28:07.48009+05:30 INFO "Initialized 0 prompts: " 
2025-12-09T08:28:07.480094+05:30 INFO "Initialized 1 promptsets: default" 
2025-12-09T08:28:07.4801+05:30 WARN "wildcard (`*`) allows all origin to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-origins` flag to prevent DNS rebinding attacks" 
2025-12-09T08:28:07.480214+05:30 INFO "Server ready to serve!" 
2025-12-09T08:28:07.480218+05:30 INFO "Toolbox UI is up and running at: http://127.0.0.1:5000/ui"

点击界面网址，并确保网址末尾有 /ui 。这将显示一个界面，如下所示：

点击左侧的“工具”选项，查看已配置的工具，在本例中，应该只有一个工具，即 search_release_notes_bq，如下所示：

只需点击工具 (search_release_notes_bq) 即可，它应该会显示一个页面供您测试该工具。由于没有要提供的参数，您可以直接点击运行工具 来查看结果。示例运行如下所示：

MCP Toolbox for Databases 还介绍了一种 Pythonic 方式来验证和测试工具，相关文档请参阅此处。我们将跳过该部分，直接进入下一部分中的智能体开发套件 (ADK)，该套件将利用这些工具。

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

安装智能体开发套件 (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.5-flash
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.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

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

具体而言，LLMAgent（通常别名为智能体）利用大语言模型 (LLM) 作为其核心引擎来理解自然语言、推理、规划、生成响应以及动态决定如何继续或使用哪些工具，这使其非常适合灵活的、以语言为中心的任务。如需详细了解 LLM 智能体，请点击此处。

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

10. 将智能体连接到工具

我们现在将此智能体连接到工具。在 ADK 的上下文中，工具表示提供给 AI 智能体的特定能力，使其能够执行操作并与世界互动，而不仅仅是其核心文本生成和推理能力。

在本例中，我们现在将为 Agent 配备我们在 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.5-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"

理想情况下，您应该会看到服务器已能够连接到我们的数据源，并且已加载工具集和工具的输出。

MCP 服务器成功启动后，在另一个终端中，通过以下 adk run （从 my-agents 文件夹中）命令启动智能体。您也可以根据需要使用 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 for Databases，并配置了 BigQuery 数据集以供 MCP 客户端访问。