bq MCP adk

BigQuery MCP ADK代理

该项目实现了一个使用模型上下文协议（MCP）与BigQuery交互的Google ADK代理。它使用 mcp-toolbox 二进制作为MCP服务器，为代理提供BigQuery工具。

演示

BigQuery Agent Demo

建筑

Architecture Diagram

先决条件

• Python 3.12+
• uv 包管理器
• 具有BigQuery访问权限的项目的Google Cloud凭据。
• mcp-toolbox 二进制文件（下载到项目根目录）。

- 下载： toolbox - 命令： curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v0.7.0/linux/amd64/toolbox && chmod +x toolbox

配置

代理需要环境变量进行配置。这些是从以下位置加载的 bq_mcp_adk/.adk/.env.

中的必需变量 .env:

• GOOGLE_CLOUD_PROJECT：您的谷歌云项目ID（例如。， wortz-project-352116).
• GOOGLE_CLOUD_LOCATION：该区域（例如。， us-central1).

运行时变量（在验证脚本中自动设置）：

• BIGQUERY_PROJECT：BigQuery查询的项目ID。此设置用于验证 wortz-project-352116 在 verify_agent.py.

安装

1. 安装依赖项:

   uv sync

1. 确保 mcp-toolbox 可执行:

   chmod +x toolbox

用法

运行验证

要测试代理并验证它可以在BigQuery中列出表：

uv run python verify_agent.py

此脚本：

1. 加载环境变量。
2. 初始化 bq_mcp_agent.
3. 连接到本地 mcp-toolbox 服务器通过stdio。
4. 任务代理“列出项目wortz-project-352116的mcd_data数据集中的表”。
5. 打印代理的响应。

代理结构

• bq_mcp_adk/agent.py：定义 root_agent 并执行 MCPToolset 配置。
• verify_agent.pyA. InMemoryRunner 用于测试代理的脚本。
• toolbox：编译的MCP服务器二进制文件。

故障排除

• 404型号未找到：确保中定义的模型 agent.py （目前 gemini-2.5-flash)在您的项目和地区可用。
• 身份验证错误：确保您具有有效的应用程序默认凭据(gcloud auth application-default login)或环境可用的有效服务帐户密钥。

项目结构

.
├── bq_mcp_adk
│   ├── agent.py       # Defines the root_agent and MCP configuration
│   └── __init__.py    # Exposes root_agent
├── README.md          # Project documentation
├── toolbox            # MCP server binary
├── verify_agent.py    # Verification script for the agent
├── pyproject.toml     # Project dependencies
└── main.py            # Entry point (optional)