skills 仓库实战：使用 BigQuery MCP 服务器让 Agent 安全地查询与分析数据
【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills
在 skills/cloud/bigquery-basics 这一 BigQuery 基础技能中，MCP（Model Context Protocol）是与bq命令行、客户端库并列的第三种操作 BigQuery 的方式。本篇以 MCP Usage 参考文档为核心，完整拆解 BigQuery 官方远程 MCP 服务器提供的 5 个工具、execute_sql的安全边界与审计标签机制，以及 MCP Toolbox 等替代连接方案，帮助你在 Agent 工作流中可靠、可审计地接入 BigQuery。
背景：为什么 BigQuery 要提供 MCP 服务器
MCP 是一种让大语言模型客户端（如 Gemini CLI、Claude Code 等）以结构化工具调用方式访问外部系统的协议。对于 BigQuery 这样的数据平台，核心概念文档 指出其资源遵循"项目 → Dataset → Table/View"的层级结构，Agent 要完成分析任务，通常需要先"看清"有哪些数据集和表，再执行 SQL。
BigQuery 通过一个**远程 MCP 服务器（remote server）**支持这一流程：服务器托管在 Google 基础设施上，客户端无需本地安装组件，直接以 HTTP 方式连接。相比让 Agent 去拼bq query命令或手写 REST 请求，MCP 工具调用参数结构化、返回结果可直接进入模型上下文，显著降低了 Agent 出错面。这也是 skills 仓库 中多个云服务技能（BigQuery、Cloud Storage、Spanner、Cloud SQL 等）统一采用"CLI + 客户端库 + MCP"三路径参考组织方式的原因，可对照 Cloud Storage MCP 参考 查看同一套"远程托管服务器 vs 本地 MCP Toolbox"模式在其他产品上的应用。
MCP 服务器提供的 5 个工具
官方参考文档 列出了 BigQuery 远程 MCP 服务器的完整工具集，共 5 个，覆盖元数据探查与查询执行两类能力：
| 工具 | 功能说明 |
|---|---|
list_dataset_ids | 列出 Google Cloud 项目中的 BigQuery 数据集 ID |
get_dataset_info | 获取指定数据集的元数据信息 |
list_table_ids | 列出指定数据集中的表 ID |
get_table_info | 获取指定表的元数据信息 |
execute_sql | 在项目内运行 SQL 查询并返回结果（仅允许SELECT，见下文详解） |
可以看出工具集的设计逻辑：前 4 个是只读元数据工具，构成 Agent 的"数据探查"能力——先list_dataset_ids找到数据集，再get_dataset_info/list_table_ids/get_table_info逐层下钻确认表结构；第 5 个execute_sql则是唯一的"数据面"入口。Agent 基于这些元数据可以自动完成"自然语言问题 → 生成 SQL → 执行 → 解读结果"的闭环。
execute_sql 的安全边界
execute_sql是整个服务器中唯一可能产生数据影响面的工具，因此文档对其做了严格约束，这也是接入该服务器时必须理解的要点：
- 仅允许
SELECT语句。INSERT、UPDATE、DELETE语句以及存储过程（stored procedures）均被禁止；如果提交的查询中不包含SELECT语句，工具会直接返回错误。这意味着 Agent 通过 MCP 通道无法修改、写入或删除任何 BigQuery 数据，写入类需求必须改走bqCLI 或客户端库等受你直接控制的路径。 - 查询仍可能有副作用。虽然语句层面被限制为只读，但文档特别提示：如果查询调用了远程函数（remote functions）或 Python UDF，仍可能产生副作用。启用该服务器时应在项目内审查已注册的远程函数与 Python UDF，避免它们被
SELECT间接触发。 - 计费归属明确。所有通过
execute_sql执行的查询都会计费到project_id字段所指定的项目。配置客户端时应确认project_id指向预期项目，避免查询成本落到错误的项目账单上。
审计标签：用goog-mcp-server: true过滤 MCP 来源查询
文档中一个非常实用的细节是：所有经由execute_sql执行的查询都会被自动打上一个标签（label），用于标识"该查询来源于 MCP 服务器"。你可以通过标签键值对goog-mcp-server: true在查询监控中过滤出这类查询。
这个能力有两个直接用途：
- 用量审计：在 BigQuery 的查询日志/作业信息中按该标签过滤，即可区分哪些查询是 Agent 通过 MCP 发起的，哪些是人类直接执行的；
- 成本归因：结合
project_id计费规则，可以精确核算 MCP 自动化查询消耗的处理字节数。
结合本技能的上报标签：为 MCP 请求追加 User-Agent
需要区分的是，goog-mcp-server: true是服务器为查询打的产品标签，而 skills 仓库 的SKILL.md中另有一套用量归因（attribution）机制，两者互不冲突、可以叠加。该要求规定：所有直接 HTTP 调用 BigQuery API 的请求，或对 MCP 服务器的 HTTP 请求，都必须在现有User-Agent头末尾追加固定字符串：
User-Agent: <existing_user_agent> agent-skills/1.0 (skill:bigquery-basics)agent-skills/<version>与skill:<name>两个 token 会被采集管道解析，因此措辞不可改动。这一点与gcloud命令的归因前缀（CLOUDSDK_METRICS_REQUEST_ATTRIBUTION环境变量）共同构成该技能的可观测性约定。同时文档也明确约束：这些归因前缀只用于你在终端直接执行的命令，不要写进交付给用户的脚本或模板。
连接设置
连接 BigQuery 远程 MCP 服务器的完整客户端配置步骤，官方指引在 Google Cloud 文档的 "Configure a client connection" 章节（参见 mcp-usage.md 中 "Setup Instructions" 一节的指向）。从仓库中同类技能的配置样例可以推断其典型形态：在 MCP 客户端的服务器列表中新增一个 HTTP 类型的条目，填入 BigQuery MCP 端点 URL，并配置 OAuth 2.0 认证信息。例如 skills 仓库 中的plugins/cloud/google-cloud-developer/mcp_config.json就展示了为客户端声明一个远程 MCP 服务器的标准结构（mcpServers→ 服务器名 →serverUrl）；BigQuery 的接入方式与之同构，区别在于需要额外的 OAuth/IAM 认证头。配置完成后，客户端会列出上文的 5 个工具供 Agent 调用。
支持的操作场景
文档归纳了基于 BigQuery MCP 远程服务器的 Agent 可执行任务：
- 通过生成并运行 SQL 回答数据问题——这是最典型的 NL2SQL 工作流，前 4 个元数据工具为 SQL 生成提供表结构与字段依据；
- 获取数据集元数据——
list_dataset_ids+get_dataset_info； - 获取表元数据——
list_table_ids+get_table_info。
一个典型的探查链路是：list_dataset_ids（项目有哪些数据集）→list_table_ids（某数据集有哪些表）→get_table_info（表的列与模式）→execute_sql（基于确认过的模式写SELECT）。由于元数据工具与查询工具由同一个服务器提供，Agent 可以在一次会话内完成"看清结构再查数"，无需人工切换工具。
替代方案：MCP Toolbox 与 BigQuery Data Analytics 扩展
参考文档 的末尾给出两条替代/增强路径：
- MCP Toolbox：一个开源的本地 MCP 服务器命令行工具，可以在本地为 BigQuery 连接拉起 MCP 服务。适合你希望服务器跑在本机（stdio 传输）、需要本地凭证管理或本地工具链集成的场景。对照仓库内 Cloud Storage MCP 参考 的选型表可以推断二者的分工逻辑：远程托管服务器免安装、带服务端安全护栏，适合元数据探查和小查询；本地 Toolbox 则便于接入更丰富的本地操作。对于 BigQuery 而言，远程服务器已覆盖"元数据 + SELECT 查询"的核心诉求，本地 Toolbox 主要补足托管端点不可用或需要自定义工具集的情形。
- BigQuery Data Analytics 扩展：面向 Gemini CLI 以及 Claude Code / Codex 的插件，提供更多专门的技能与高级分析工作流。当你需要的不只是单条 SQL，而是成体系的分析流程时，可在 MCP 服务器之上叠加该扩展。
与仓库中其他 BigQuery 操作路径的关系
bigquery-basics技能将 MCP 定位为与 CLI、客户端库互补的路径，选型时可对照：
bqCLI（cli-usage.md）：管理数据集、建表（bq mk --table ... schema.json）、加载数据（bq load）、作业管理（bq ls -j/bq show -j/bq cancel）等资源管理操作，MCP 服务器不覆盖这些写操作——例如 MCP 只能列数据集，而bq mk --dataset --location=us my_dataset才能建数据集；查询方面 CLI 支持--dry_run预估处理字节数，是成本控制手段；- 客户端库（client-library-usage.md）：Python、Java、Node.js、Go 等语言的程序化集成，适合把 BigQuery 查询固化进应用代码；
- MCP 服务器（本文主题）：面向 Agent 会话的结构化查询入口，只读、可审计、带审计标签。
综合来看，推荐组合是：资源生命周期管理走 CLI 或 IaC，应用内集成走客户端库，Agent 的交互式数据问答走 MCP——execute_sql的SELECT白名单与goog-mcp-server: true标签正是为了让"Agent 自主查询"这件事在安全与成本上都可预期。
小结
BigQuery MCP 服务器以 5 个工具提供了"元数据探查 + 只读查询"的完整闭环：list_dataset_ids、get_dataset_info、list_table_ids、get_table_info负责让 Agent 看清数据结构，execute_sql负责执行仅SELECT的查询并自动携带goog-mcp-server: true审计标签，计费落到project_id指定项目。接入时注意两点：一是确认项目内远程函数/Python UDF 不会引入查询副作用，二是按 SKILL.md 的约定为对 MCP 服务器的 HTTP 请求追加agent-skills/1.0 (skill:bigquery-basics)归因前缀。若需要更灵活的本地服务器或成体系的高级分析工作流，可分别参考 MCP Toolbox 与 BigQuery Data Analytics 扩展。
【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
