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

1. 简介

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

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

1. 从 BigQuery 公共数据集计划中确定一个特定的 BigQuery 数据集（“Google Cloud 发行说明”）。
2. 设置 MCP Toolbox for Databases，以连接到 BigQuery 数据集。
3. 使用智能体开发套件 (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. 准备工作

创建项目

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

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

gcloud auth list

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

gcloud config list project

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

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 工具，让智能体能够访问数据库中的数据。工具箱提供：

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

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

简单来说：

1. MCP Toolbox 以二进制文件、容器映像的形式提供，您也可以从源代码构建它。
2. 它公开了一组可通过 tools.yaml 文件配置的工具。您可以将这些工具视为连接到数据源。您可以看到它支持的各种数据源：AlloyDB、BigQuery 等。
3. 由于此工具箱现在支持 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.13.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

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

7. 配置 MCP Toolbox for Databases

现在，我们需要在 MCP Toolbox for Database 所需的 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

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

1. 来源表示工具可以与之互动的不同数据源。来源表示工具可以与之互动的数据源。您可以在 tools.yaml 文件的 sources 部分中将来源定义为映射。通常，来源配置将包含连接数据库并与之互动所需的任何信息。在本例中，我们定义了一个 BigQuery 来源 my-bq-source，您需要提供自己的 Google Cloud 项目 ID。如需了解详情，请参阅来源参考文档。
2. 工具定义了代理可以执行的操作，例如读取和写入来源。工具表示代理可以执行的操作，例如运行 SQL 语句。您可以在 tools.yaml 文件的 tools 部分中将工具定义为映射。通常，工具需要一个源才能发挥作用。在本例中，我们定义了一个工具 search_release_notes_bq。这会引用我们在第一步中定义的 BigQuery 来源 my-bq-source。它还包含 AI 代理客户端将使用的陈述和指令。如需了解详情，请参阅工具参考文档。
3. 最后是工具集，可让您定义要能够一起加载的工具组。这有助于根据代理或应用定义不同的群组。在本例中，我们有一个工具集定义，其中目前仅定义了一个现有工具 search_release_notes_bq。您可以拥有多个工具集，每个工具集包含不同的工具组合。

因此，目前我们只定义了一个工具，用于根据查询获取过去 7 天的发布说明。不过，您也可以将参数与各种其他元素组合使用。

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

8. 测试 MCP Toolbox for Databases

我们已下载并配置了工具箱，其中包含 mcp-toolbox 文件夹中的 tools.yaml 文件。我们先在本地运行它。

执行以下命令：

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

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

2025-09-08T03:56:45.772489914Z INFO "Initialized 1 sources." 
2025-09-08T03:56:45.772682659Z INFO "Initialized 0 authServices." 
2025-09-08T03:56:45.772735103Z INFO "Initialized 1 tools." 
2025-09-08T03:56:45.772774639Z INFO "Initialized 2 toolsets." 
2025-09-08T03:56:45.777711644Z 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.13.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 界面测试工具

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

如果您想测试一下，可以运行之前用于启动 Toolbox 服务器的命令，并添加 --ui 选项。

为此，请关闭您可能正在运行的 MCP Toolbox for Databases Server 的上一个实例，然后运行以下命令：

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

理想情况下，您应该会看到输出，表明服务器已成功连接到我们的数据源，并已加载工具集和工具。以下是示例输出，您会注意到其中提及了 Toolbox 界面已启动并正在运行。

2025-09-08T03:59:34.856476253Z INFO "Initialized 1 sources." 
2025-09-08T03:59:34.856546526Z INFO "Initialized 0 authServices." 
2025-09-08T03:59:34.856577586Z INFO "Initialized 1 tools." 
2025-09-08T03:59:34.856641568Z INFO "Initialized 2 toolsets." 
2025-09-08T03:59:34.86133344Z INFO "Server ready to serve!" 
2025-09-08T03:59:34.861366205Z INFO "Toolbox UI is up and running at: http://localhost:5000/ui" 

点击界面网址，确保网址末尾有 /ui。系统会显示如下界面：

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

只需点击工具图标 (search_release_notes_bq)，系统即会显示一个页面，供您测试该工具。由于无需提供任何参数，您只需点击运行工具即可查看结果。运行示例如下所示：

MCP Toolkit for Databases 还介绍了一种以 Python 方式验证和测试工具的方法，相关文档请参阅此处。我们将在下一部分中跳过这些工具，直接进入将使用这些工具的智能体开发套件 (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 命令（应用名称为 **(gcp-releasenotes-agent-app)**，如下所示）为 Google Cloud 版本说明代理应用创建脚手架。

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 智能体。

至此，我们已完成使用智能体开发套件 (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 文件夹）命令启动代理。您也可以根据需要使用 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 数据库工具箱，并配置了可在 MCP 客户端中访问的 BigQuery 数据集。

参考文档

• MCP Toolbox for Databases
• BigQuery 公开数据集