BigQuery Data Platform

BigQuery MCP

一个通过 Model Context Protocol 连接 Google BigQuery 的只读服务。 它让 AI 客户端（Claude Code、Claude Desktop，……）能够通过发现架构并运行 SELECT 查询来回答自然语言数据问题。

AI 负责将自然语言转换为 SQL；此服务只使用你自己的 Google 凭据，安全地执行查询。

• 文档： https://debilla.github.io/bigquery-mcp/
• 仓库： https://github.com/deBilla/bigquery-mcp
• PyPI： data-platform-mcp
• MCP 注册表： mcp-name: io.github.deBilla/data-platform-mcp

---

提供的工具

工具	用途	费用
list_datasets	列出项目中的数据集	免费
list_tables	列出数据集中的表/视图	免费
get_table_schema	列（展开嵌套路径）、分区信息、大小、行数	免费
check_table_freshness	每个表最近一次写入时间 — 发现过时的数据源	免费
list_environments	配置了哪些 BigQuery 环境，以及默认环境	免费
list_scheduled_queries	哪个计划查询会写入某张表，以及它是否已停用或运行失败	免费
get_scheduled_query	某个查询的 SQL、目标位置和近期运行记录	免费
list_code_assets	BigQuery Studio 中的笔记本、保存的查询和数据画布	免费
get_code_asset	某个笔记本或保存的查询的内容；已剥离笔记本输出	免费
find_code_assets_using_table	哪些笔记本/保存的查询会读取某张表	配额，不收费
list_notebook_schedules	计划运行的 Colab 笔记本，以及近期运行失败的次数	免费
list_notebook_runs	所有计划任务中的单次笔记本运行记录 — 默认显示失败记录	免费
get_notebook_schedule	某个计划任务的 cron 表达式、笔记本和近期错误	免费
run_query	运行经过验证的只读 SELECT 并返回行	扫描数据

只有 run_query 会产生费用，因此应优先使用发现工具。其中有两个工具专门用于避免特定的常见错误：

• get_table_schema 根据表元数据报告分区信息，绝不根据列名判断。 表中有一个 partition_date 列，并不代表它已分区 — 如果没有分区，任何 WHERE 子句都无法减少扫描量，每个查询都会读取整张表。表较大时，响应会明确标出这一点。
• check_table_freshness 会找出已停止写入、但尚未删除的表。 这些表会返回过时数据，而不是错误 — 这是最容易被忽视的故障模式。
• find_code_assets_using_table 回答了问题的另一面。 计划查询工具会说明哪些内容在写入某张表；此工具会说明哪些内容在读取它，这是更改架构前需要了解的问题。它也是唯一不免费的发现工具：它会打开所检查的每个资源，消耗 Dataform 读取配额，因此设有上限，并会报告实际检查了项目的多少内容。结果只能作为已扫描资源的依据，绝不能证明没有其他内容在使用该表 — 无法读取的资源会单独列出，而不会计为未发现。
• list_scheduled_queries 会说明原因。 表过时通常是因为计划查询已停用或运行失败，而这些信息位于另一个 API（BigQuery Data Transfer）中，需要 roles/bigquerydatatransfer.viewer 角色。没有该角色时，这两个工具会返回指出该角色的错误，其他功能仍会正常工作。大多数计划查询不会声明目标位置，因为它们通过 DDL 写入，因此目标会从 SQL 中读取，并以 writes_to_from_sql 报告 — 这是一个启发式结果，也会明确标注。

---

BigQuery Studio 笔记本和已保存的查询

这些不是 BigQuery 资源。BigQuery Studio 会将每个代码资产存储为一个仅包含单个文件的 Dataform 仓库，这意味着除了 BigQuery 和 Data Transfer Service 之外，还需要第三个 API 和第三项权限——roles/dataform.viewer。如果没有这项权限，三个工具都会返回一条指出该角色的错误，其他功能则一切正常。它们在 Dataform 界面中也不可见，因此控制台里没有任何提示能说明它们存放在哪里。

配置之前，有两点关于这种存储方式值得了解：

• 代码资产位于区域级位置，并非数据集所在的区域。 Dataform 不接受多区域，因此数据集位于 US 的平台会将笔记本存放在类似 us-central1 的位置。**无需进行任何配置：**当 location 为多区域时，服务会探测其中的区域，使用存放资产的区域，并说明所用位置——无法直接继承多区域，因为使用多区域一定会失败，而非仅有可能失败。指定 code_asset_location（或 BQ_CODE_ASSET_LOCATION）可跳过探测；明确指定的值不会被重新核验，因此错误的值会返回空列表，而非报错。每个结果都会回显读取时使用的位置。

• **笔记本正文大多是输出内容。**在 52 个真实笔记本中，单元格输出占字节数的 77%——其中一个文件有 1.44 MB，而代码只有 80 KB。返回任何内容之前都会剥除输出，并报告节省的空间，让你知道被移除的是渲染后的图表，而非逻辑代码。

读取受容量配额限制，而非并发量限制，且配额会在几十秒内补充。配额耗尽时，系统会进行退避重试；如果仍未恢复，则会报告稍后重试，而非报告失败。

---

计划运行的 Colab 笔记本

BigQuery Studio 中的笔记本可以设置计划，而计划运行往往会在无人关注的情况下进行：没有任何报告，因此笔记本可能连续数周每晚运行失败，唯一的迹象就是某张表悄然停止更新。在本平台所基于的环境中，7,061 次运行里有 354 次失败，却完全没有显现出来。

要回答一个问题，就必须联查三个资源，这也是难以发现问题的主要原因。计划是 Vertex AI Schedule（cron、时区、是否暂停）；每次运行都是一个 NotebookExecutionJob；笔记本则是 list_code_assets 列出的同一个 Dataform 代码资产——因此，计划运行失败时，可以直接通过 get_code_asset 找到失败的代码。这意味着要调用第四个 API，并额外授予 roles/aiplatform.viewer 权限。没有此权限时，三个工具会返回指出该角色的错误，其他功能则照常运行。无需新增依赖：这里通过 REST 与 Vertex AI 通信，不会为了两个列表端点引入 google-cloud-aiplatform。

在信任所见结果之前，有三点值得了解：

• 笔记本运行失败时，计划仍会报告自身状态健康。 49 个正在运行的计划都将最近一次计划运行报告为 OK，其中包括一个此前连续 79 次运行都失败的计划。OK 表示调度器成功启动了作业，而不是笔记本运行成功。控制台首先显示的就是这个字段，也正是因此问题一直未被发现，所以这里始终根据执行作业计算运行状态，绝不会将计划自身的状态作为运行结果报告。与此同时，PAUSED 是笔记本生成的表数据过时的最常见原因。

• 无法在服务端按运行结果筛选。 Vertex AI 会直接拒绝 jobState 筛选条件，并将分页上限设为 100，因此“显示失败项”意味着读取各页数据后在本地筛选。运行记录确实按时间从新到旧排序，因此可以用有限的时间窗口来控制开销：lookback_days（默认为 30 天，让按月运行的计划至少显示一次运行记录）会在达到时间范围时停止遍历，而不是扫描一整年的历史记录。30 天约需调用 API 7 次，90 天约需 23 次。

• 运行记录的保留时间会超过创建它们的计划。 删除并重新创建计划是编辑计划的常规方式，因此 7,061 条仍存在的运行记录引用了 75 个不同的计划，其中只有 49 个仍然存在。这些运行记录都是真实记录，失败也计入统计，因此会标注为 (schedule no longer exists)，而不是直接丢弃。出于同样的原因，显示名称并不唯一——两个仍在运行的计划使用了同一个名称，因此遇到名称歧义时会报错并列出候选项及其 ID，绝不会悄悄选择第一个匹配项。

data-platform-mcp doctor 会报告可读取的计划数量、已暂停的计划数量，以及上周失败的计划数量。

---

环境

一个服务可以回答有关多个目标的问题，例如数据仓库及其暂存副本，或同一项目中的两个区域。每个工具都接受可选的 environment；省略时会使用默认环境。

# ~/.config/data-platform-mcp/config.toml
default_environment = "warehouse"

[environments.warehouse]
project = "my-data-platform"
impersonate = "[email protected]"
dataset_allowlist = ["sales", "events"]

[environments.central]          # same project, different region
project = "my-data-platform"
location = "us-central1"

所有设置请参见 config.toml.example，也可以将相同结构的 JSON 设置为 BQ_MCP_ENVIRONMENTS。单个 BQ_PROJECT 仍可照常使用——它会成为一个名为 default 的环境。

环境可以通过其名称、别名、内置简称（prod、stg、dev、live）或项目 ID 来指定。名称未知时会报错并列出有效选项，绝不会悄悄回退到默认环境：如果拼写错误导致原本针对生产环境的问题从暂存环境获取答案，回复中将无法察觉。每个结果都会回显其来源环境。

区域是这里最需要关注的问题。BigQuery 无法跨位置查询，而尝试跨位置查询时返回的错误不会指出位置，因此看起来就像缺少表。每个位置对应一个环境；doctor 会报告各数据集所在的位置。

---

身份的只读属性

仅允许 SELECT 的防护措施和 readOnlyHint 注解是对这段代码的承诺。让服务器指向一个只拥有 roles/bigquery.jobUser 和数据集级 roles/bigquery.dataViewer 的服务账号，就能让只读成为凭据本身的事实——无论代码如何运行，也无论你自己的角色具有什么权限，IAM 都会强制执行：

data-platform-mcp setup --project my-data-platform --datasets sales,events

创建该账号，授予这两个角色，并为你授予该账号上的 roles/iam.serviceAccountTokenCreator，以便服务器模拟该账号。 添加 --dry-run 可先查看命令；可以安全地重复运行。

使用 --datasets 后，数据集允许列表就不再是此进程中的一条 if 语句，而会成为由 Google 强制执行的授权。

---

macOS 设置

Terminal.app 不是 Xcode。 每台 Mac 都预装了它。Xcode Command Line Tools 则不是预装组件，而分析师的笔记本电脑通常既没有这些工具，也没有 Homebrew。这里的操作不需要它们——但很容易误触，因为 git、make、clang 和系统自带的 /usr/bin/python3 都是该工具包的占位程序：运行其中任何一个都会弹出系统对话框，提示安装大约 1 GB 的开发工具。

下面的命令都不会调用这些程序。它们只使用 macOS 已有的工具——curl、tar、sh、uname——因为这两种安装方式都是独立完整的：

安装项	为何不需要其他工具
uv	独立二进制文件。其安装程序不会提及 Python，并且会自行下载 Python 来运行服务器。
Google Cloud CLI	macOS tarball 包含自己的 Python（.install/bundled-python3-unix-darwin-*）。

终端操作只需执行下面三个代码块，各一次。

1. 安装 uv

curl -LsSf https://astral.sh/uv/install.sh | sh
which uvx      # note this absolute path — Claude Desktop will need it

通常位于 /Users/<you>/.local/bin/uvx。

2. 安装 Google Cloud CLI

根据你的芯片选择对应版本——uname -m 在 Apple Silicon 上会输出 arm64，在 Intel 上会输出 x86_64：

# Apple Silicon
curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-arm.tar.gz
tar -xzf google-cloud-cli-darwin-arm.tar.gz

# Intel — same, with the other file
# curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-x86_64.tar.gz
# tar -xzf google-cloud-cli-darwin-x86_64.tar.gz

./google-cloud-sdk/install.sh --quiet

请避免使用 brew install --cask google-cloud-sdk：Homebrew 本身需要 Command Line Tools，而本节正是为了避免安装它们。

3. 身份验证

./google-cloud-sdk/bin/gcloud auth application-default login
./google-cloud-sdk/bin/gcloud auth application-default set-quota-project your-gcp-project

这会写入一个 Google 库可直接读取的凭据文件。 之后不需要将 gcloud 添加到 PATH——这里只需用一次。这就是为什么即使通过 GUI 启动的 Claude Desktop 无法访问你的 shell，它仍然可以查询 BigQuery。

你的账号需要在运行查询的项目上拥有 BigQuery Job User 权限，并在其读取的每个数据集上拥有 BigQuery Data Viewer 权限——这些项目通常并不相同。

4. 检查是否成功

BQ_PROJECT=your-gcp-project uvx data-platform-mcp doctor

然后向你的客户端注册：Claude Desktop 或 Claude Code。

替代方案：分析师完全不使用终端

如果连这些操作都嫌麻烦，管理员可以集中处理凭据部分，分析师只需安装 uv——完全跳过第 2 步和第 3 步。 （这并非 macOS 专属方案；在任何操作系统上都一样适用。）

# the admin, once, on their own machine
data-platform-mcp setup --project your-gcp-project --datasets sales,events
gcloud iam service-accounts keys create analyst-key.json \
  --iam-account [email protected]

分析师保存该文件，并在配置中指向它：

{
  "mcpServers": {
    "bigquery": {
      "command": "/Users/YOU/.local/bin/uvx",
      "args": ["data-platform-mcp@latest"],
      "env": {
        "BQ_PROJECT": "your-gcp-project",
        "GOOGLE_APPLICATION_CREDENTIALS": "/Users/YOU/keys/analyst-key.json"
      }
    }
  }
}

这种权衡确实存在，值得明确说明。 密钥文件是长期有效的凭据，会存放在笔记本电脑上；而 gcloud auth application-default login 签发的是与个人绑定的短期令牌。在这里使用密钥是可以接受的，因为由 setup --datasets 创建的账号只能读取你指定的数据集，而且笔记本电脑丢失后可以立即在中央吊销密钥——但这种方式的安全性确实较弱，并且密钥是每位分析师各自的秘密，因此不要将它放进共享配置文件或代码仓库。

---

Linux

同样安装这两个组件，而且不存在类似 Command Line Tools 的问题：

curl -LsSf https://astral.sh/uv/install.sh | sh
curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz
tar -xzf google-cloud-cli-linux-x86_64.tar.gz
./google-cloud-sdk/install.sh --quiet
./google-cloud-sdk/bin/gcloud auth application-default login

然后检查是否成功，并向你的客户端注册。

---

Windows

未经端到端验证。 已检查下面的下载 URL 和安装位置，但尚未在 Windows 机器上实际运行这一流程。CI 只测试 Linux。请将其视为经过仔细推导的操作说明，而非经过测试的步骤——如果发现任何步骤有误，请提交 issue。

1. 安装 uv

在 PowerShell 中：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

这会将 uv.exe 和 uvx.exe 安装到 %USERPROFILE%\.local\bin。确认 准确路径，因为桌面端配置需要填写完整路径：

(Get-Command uvx).Source

2. 安装 Google Cloud CLI

下载并运行 GoogleCloudSDKInstaller.exe。 保留勾选 "Bundled Python"——这样 SDK 就能在不单独安装 Python 的情况下运行，与 macOS tarball 具备相同特性。

3. 进行身份验证

在新的 PowerShell 窗口中运行，以便加载更新后的 PATH：

gcloud auth application-default login
gcloud auth application-default set-quota-project your-gcp-project

这会将凭据写入 %APPDATA%\gcloud\application_default_credentials.json，Google 库会直接读取该文件，因此之后无需将 gcloud 添加到 PATH。

4. 检查是否成功

$env:BQ_PROJECT="your-gcp-project"; uvx data-platform-mcp doctor

5. 配置 Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json——如果文件不存在，请创建。 JSON 中的反斜杠必须加倍，且路径必须是绝对路径：

{
  "mcpServers": {
    "bigquery": {
      "command": "C:\\Users\\YOU\\.local\\bin\\uvx.exe",
      "args": ["data-platform-mcp@latest"],
      "env": {
        "BQ_PROJECT": "your-gcp-project"
      }
    }
  }
}

将 C:\Users\YOU\... 替换为 (Get-Command uvx).Source 输出的路径，并将每个 \ 写成 \\。然后完全退出并重新打开 Claude Desktop。

如果失败，日志位于 %APPDATA%\Claude\logs\。其中的 ENOENT 表示 command 路径有误，或反斜杠未加倍——与 macOS 上的故障相同，只是多了一种出错方式。

---

快速开始（每位用户）

每个人都运行自己的本地副本。查询会使用各自的 BigQuery/IAM 权限执行，因此现有访问控制会决定每个人能查看哪些内容。

请先为你的平台安装先决条件——macOS、 Linux、Windows——然后再回到这里。

1. 安装

该软件包以 data-platform-mcp 发布（bigquery-mcp 已被 PyPI 上一个无关项目 占用）。无需检出仓库——客户端可以直接获取并运行它：

uvx data-platform-mcp --version

从源代码安装，用于开发：

git clone [email protected]:deBilla/bigquery-mcp.git
cd bigquery-mcp

python3 -m venv .venv
./.venv/bin/pip install -e .

无论采用哪种方式，都会得到一个 data-platform-mcp 命令，客户端会运行该命令。

2. 向 Google 进行身份验证（一次性）

上述平台部分已介绍此操作：macOS 第 3 步，或在其他平台上运行 等效的 gcloud auth application-default login。之后，查询会通过 Application Default Credentials 使用你自己的凭据执行。

改用服务账号密钥？ 将 GOOGLE_APPLICATION_CREDENTIALS 设为密钥路径——但要在启动 MCP 服务的环境中设置，而不是在 shell 中设置：

// in your client's MCP config, alongside BQ_PROJECT
"env": {
  "BQ_PROJECT": "your-gcp-project",
  "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/key.json"
}

客户端会将服务作为子进程启动，并且只传入其配置中声明的环境变量。在终端中导出该变量不会对它生效——这与完全没有凭据是不同的故障，但从外部看起来一模一样。

3. 检查设置

BQ_PROJECT=your-gcp-project data-platform-mcp doctor

检查凭据、作业权限、数据集可见性，以及——最容易让人忽略的一项——数据集区域。 BigQuery 无法查询位于其他位置的数据集，而且其报错既不指出所需位置，也不指出数据集所在位置，因此看起来像是缺少表。doctor 会列出两者：

[  ok  ] run a query in my-project (location US)
[  ok  ] 39 datasets visible (no allowlist; all are readable)
[ warn ] 6 of 39 datasets are outside location US
         US-CENTRAL1: analytics_raw, business_data, ds_public, pg_public, public, recommendations
         BigQuery cannot query these from US, and cannot join them with
         datasets that are in it.
         Fix:  set BQ_LOCATION to the region you need, and run a separate
               server for datasets in another one.

位于其他区域的数据集会产生警告；位于 BQ_DATASET_ALLOWLIST 中的数据集则会导致失败，因为任何工具调用都无法读取它。

4. 注册到 AI 客户端

将 your-gcp-project 替换为你的 GCP 项目 ID。

Claude Code——发布后：

claude mcp add bigquery \
  --env BQ_PROJECT=your-gcp-project \
  -- uvx data-platform-mcp

从源代码安装时，改为指向检出目录（替换 /abs/path/bigquery-mcp）：

claude mcp add bigquery \
  --env BQ_PROJECT=your-gcp-project \
  -- /abs/path/bigquery-mcp/.venv/bin/data-platform-mcp

Claude Desktop——请参阅下方专门章节；它需要绝对路径。

5. 重启客户端并提问

“有哪些数据集可用？在 sales 数据集中，orders 表有多少行？”

---

Claude Desktop

数据团队中的大多数人会使用 Desktop，而不是 CLI；它还有一种 CLI 不会遇到的 故障模式。

Claude Desktop 不会继承你的 shell PATH。 它从 Finder 启动，因此 uvx、python 以及通过 Homebrew 或 uv 安装的任何程序对它来说都不可见。 配置中写着 "command": "uvx" 时会因 ENOENT 而失败——服务根本不会启动， 而错误指出的是命令，而不是原因。此文件中的每个路径都必须是绝对路径。

不会出问题的是：凭据。应用默认凭据是一个 Google 库会直接读取的文件，因此查询 无需 gcloud 位于 PATH 中即可运行——只需在终端中运行一次 gcloud 来创建 该文件。已通过在完全空的环境中运行此服务进行验证：查询成功。

1. 安装并进行身份验证

先完成平台设置——macOS（粘贴两条命令，无需 Xcode 工具），或 Linux、Windows。你需要其中两项信息：which uvx 打印的绝对路径，以及已完成的 gcloud auth application-default login。

2. 编辑配置

Claude Desktop 的设置 → 连接器会列出托管连接器；像这样的本地 服务不会添加在那里，而是写入 JSON 文件：

设置 → 开发者 → 编辑配置会打开该文件。也可以直接编辑：

操作系统	文件
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

此文件通常已经存在，并保存着你的 Desktop 偏好设置。 将 mcpServers 作为另一个顶层键添加进去——不要替换该文件，否则会 丢失这些设置。如果文件确实不存在，则只需用下面的代码块创建它。

{
  "mcpServers": {
    "bigquery": {
      "command": "/Users/YOU/.local/bin/uvx",
      "args": ["data-platform-mcp@latest"],
      "env": {
        "BQ_PROJECT": "your-gcp-project"
      }
    }
  }
}

将 /Users/YOU/.local/bin/uvx 替换为 which uvx 打印的路径。在 Windows 上，路径看起来像 C:\\Users\\YOU\\.local\\bin\\uvx.exe，并且 JSON 中的反斜杠必须 加倍。

合并到已有设置的文件后，内容如下——mcpServers 与其他内容并列，而不是取而代之：

{
  "preferences": { "...": "your existing settings, left alone" },
  "mcpServers": {
    "bigquery": {
      "command": "/Users/YOU/.local/bin/uvx",
      "args": ["data-platform-mcp@latest"],
      "env": { "BQ_PROJECT": "your-gcp-project" }
    }
  }
}

重启前，请检查文件仍能通过解析——多余的逗号会悄无声息地禁用所有 服务：

python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

3. 重启 Claude Desktop

完全退出并重新打开——仅重新加载窗口还不够。服务会显示在消息框中的工具图标 下方。

管理多个数据仓库

与其不断扩充 JSON，不如将各个环境放入 ~/.config/data-platform-mcp/config.toml（参见 环境）。这样 Desktop 配置就完全不需要 env 块，并且在每台机器上 都相同：

{
  "mcpServers": {
    "bigquery": {
      "command": "/Users/YOU/.local/bin/uvx",
      "args": ["data-platform-mcp@latest"]
    }
  }
}

对于团队来说，这种方式更合适：共享一个配置文件，而且 JSON 中 不再需要保存项目 ID。

无法正常工作时

Desktop 会隐藏原因，因此请按以下顺序检查：

1. 在终端中运行 doctor。 它会一次性检查凭据、角色、数据集 可见性和区域；这是判断问题出在设置还是 Desktop 上最快的方法：

   BQ_PROJECT=your-gcp-project /Users/YOU/.local/bin/uvx data-platform-mcp doctor
   

2. 查看日志。 macOS：~/Library/Logs/Claude/mcp*.log。其中的 ENOENT 或 "command not found" 表示 command 路径有误——返回去检查 which uvx。
3. 检查 JSON 是否能通过解析。 末尾多余的逗号会悄无声息地禁用所有服务：

   python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

安全性

• 每个查询都会先进行 dry-run，以验证查询并估算扫描的字节数。
• 只运行 SELECT / WITH 语句——不执行写入、DDL 或 DML。
• 费用确认： 预计扫描量超过 BQ_WARN_BYTES（默认为 1 GB）的查询不会运行。系统会返回 status: "confirmation_required"，并附上预计扫描量和费用，以便客户端在继续前征求确认。重新调用时传入 confirm_expensive=true 即可运行。
• 硬性上限： 超过 BQ_MAX_BYTES_BILLED（默认为 5 GB）的查询永远不会运行，即使已确认也不例外——这是防止费用失控的最后保障。
• 可选的数据集允许列表可限制可读取的内容。
• 拒绝请求会作为协议错误处理。 对于服务拒绝执行的任何操作——非 SELECT 语句、不允许访问的数据集或超出硬性上限的查询——返回结果都会设置 MCP 的 isError，因此不会被误认为是查询结果。confirmation_required 是特意设置的例外：它属于正常结果，因为 Agent 应转达该结果并在获得确认后重试。
• 响应大小有限制。 run_query 会在序列化后的响应达到约 40k 个字符时停止添加行，并设置 stopped_for_size，以免宽结果悄然占满整个上下文窗口。部分结果一定会注明这是部分结果。
• SQL 永远不会写入审计日志——只记录哈希值和长度。查询文本通常包含用于筛选的用户 ID 或电子邮件地址。

费用确认流程

run_query(sql)
   │  dry run estimates the scan
   ├── ≤ 1 GB ........... runs, returns rows + estimated_cost_usd
   ├── 1–5 GB .......... status: confirmation_required (size + $ estimate) → ask user
   │                      → run_query(sql, confirm_expensive=true) runs it
   └── > 5 GB ........... rejected, never runs

---

配置（环境变量）

变量	默认值	含义
BQ_MCP_ENVIRONMENTS	（无）	从环境名称映射到设置的 JSON 映射。优先于配置文件。
BQ_MCP_DEFAULT_ENVIRONMENT	（最安全的环境，否则为第一个）	调用未指定 environment 时使用的环境。未设置时优先选择 staging/dev 环境。
BQ_MCP_CONFIG	~/.config/data-platform-mcp/config.toml	TOML 配置文件的路径
BQ_IMPERSONATE_SERVICE_ACCOUNT	（无）	要模拟的只读服务账号
BQ_PROJECT	（ADC 项目）	要查询其 BigQuery 数据集的 GCP 项目 ID。若未设置，则回退到与凭据关联的项目；如果两者都未设置，工具会报错并提供操作说明。
BQ_LOCATION	US	BigQuery 位置
BQ_WARN_BYTES	1073741824（1 GB）	超过此值时，运行前会要求用户确认
BQ_MAX_BYTES_BILLED	5368709120（5 GB）	每个查询的扫描量硬性上限——绝不会超出
BQ_COST_PER_TIB_USD	6.25	用于生成费用估算的按需价格
BQ_ROW_LIMIT	200	默认返回的行数
BQ_DATASET_ALLOWLIST	（空 = 全部）	以逗号分隔的数据集 ID
BQ_MCP_TRANSPORT	stdio	stdio（子进程）或 http/sse（通过网络提供服务）
BQ_MCP_HOST	127.0.0.1	传输方式为 http/sse 时的绑定主机。run-http.sh 会将其覆盖为 0.0.0.0，以便容器访问——请参阅下方的安全说明。
BQ_MCP_PORT	8765	传输方式为 http/sse 时的绑定端口
BQ_MCP_AUDIT_LOG	~/.local/state/data-platform-mcp/audit.jsonl	记录每次工具调用的 JSONL 文件。设为 off 可禁用。永远不会写入 SQL 文本——只记录哈希值和长度。
BQ_MCP_LOG_LEVEL	INFO	stderr 日志的详细程度

默认情况下，服务使用 stdio 通信——当客户端（Claude Code、Claude Desktop）启动服务时，这是合适的选择，也是上方快速开始部分采用的方式。

---

高级：通过 HTTP 提供服务

如需从远程或容器化客户端访问服务，而不是让每个客户端各自启动服务，请通过 HTTP 运行：

BQ_PROJECT=your-gcp-project ./run-http.sh
# Serving … on http://0.0.0.0:8765/mcp

然后，客户端通过 URL 连接（Claude Code）：

claude mcp add --transport http bigquery http://<host>:8765/mcp

⚠️ 安全性：HTTP 端点没有身份验证，且每个查询都使用主机的 ADC 凭据运行，而非连接用户的凭据。任何能够访问该端口的人，都可以以你的身份完整读取 BQ_PROJECT。仅在可信网络上公开此端点（绑定 BQ_MCP_HOST=127.0.0.1 并使用 SSH 隧道/VPN，或使用身份验证代理）。有关此模式旨在支持的容器化客户端设置，请参阅 docs/nanoclaw.md。

对于服务部署，请将 GOOGLE_APPLICATION_CREDENTIALS 指向具有 BigQuery Data Viewer 和 Job User 角色的服务账号密钥，而不要使用个人 ADC。

---

开发

欢迎贡献 — 请参阅 CONTRIBUTING.md，以及 good first issue 标签，寻找入门任务。

./.venv/bin/pip install -e ".[dev]"
./.venv/bin/python -m pytest

测试套件无需凭据，也无需网络 — 所有测试都使用 tests/conftest.py 中的模拟对象运行，因此结果确定且免费。各层如下：

文件	覆盖内容
test_protocol.py	通过真实的内存客户端会话验证 MCP 契约：工具集、只读注解、生成的架构、拒绝时的 isError
test_query_guard.py	成本门控 — 哪些查询会运行、哪些会被拒绝、哪些内容会返回给用户，以及调用方会收到哪些限制说明
test_payload_shape.py	使用模拟表验证响应结构，包括分区陷阱和嵌套字段展平
test_observability.py	审计记录，以及 SQL 文本绝不会进入其中的保证
test_diagnostics.py	doctor 的报告，包括它旨在及早发现的区域和允许列表错误
test_environments.py	环境间的路由、各环境的限制，以及模拟身份的目标设置
test_config.py	环境注册表、别名、TOML 文件，以及曾导致导入时崩溃的缺少项目错误
test_errors.py	身份验证失败时会附上修复该问题的命令
test_formatting.py	要求用户批准的大小和成本数据
test_eval_scoring.py	评估评分器，输入每个用例旨在拒绝的执行轨迹

评估

另外两层需要有效凭据，因此不属于 pytest 的一部分： evals/measure.py 会记录客户端实际从每个工具收到的内容，而 evals/tool_use_evals.py 会通过 claude CLI 提出真实问题，并根据服务自身的审计日志对执行轨迹评分 — 哪个工具运行了、针对哪个环境，以及使用了哪些参数。

./.venv/bin/python evals/measure.py                     # payload sizes
./.venv/bin/python evals/tool_use_evals.py              # 6 cases, spends tokens
./.venv/bin/python evals/tool_use_evals.py --rescore    # re-score saved replies, free

请参阅 evals/README.md，了解每个用例会捕获哪些问题；参阅 evals/BASELINE.md，了解上次运行测得的结果。工具和服务描述是在此服务中最值得优先调整的内容，而只有评估才能告诉你它们是否需要调整。

变异测试

首次运行就通过的测试套件无法证明任何事情，因此我们通过破坏上述保证来验证它们：将拒绝改回返回错误形状的结果、记录原始 SQL、根据列名猜测分区、移除响应预算、从审计包装器中移除 functools.wraps、允许确认绕过硬性上限、屏蔽过期表检测，以及移除允许列表检查。每项操作都会导致测试套件失败。

升级

uvx 仅在首次运行时解析最新版本，之后会无限期复用缓存的环境。若服务器配置为 ["data-platform-mcp"]，它会一直运行首次下载的构建版本：后续版本添加的工具会直接缺失，这看起来像是“此服务器无法执行该操作”，而不是尚未完成升级。添加 @latest，让每次启动时都重新解析：

"args": ["data-platform-mcp@latest"]

然后完全退出并重新打开客户端。MCP 服务会在客户端启动时生成，因此重新加载仍会让旧进程继续运行。

若要临时升级而不修改配置，可运行 uv cache clean data-platform-mcp（如果是通过 uv tool install 安装的，则运行 uv tool upgrade data-platform-mcp）。list_environments 会报告 server_version，因此你可以在对话中确认实际运行的版本。

发布

版本号位于两个文件中，CI 会拒绝版本号不一致的标签——不一致会导致发布的标签指向的代码与软件包声明的代码不同。（__version__ 从已安装的发行版中读取，因此不会出现偏差。）

# 1. bump both to the same value
#      pyproject.toml   project.version
#      server.json      version  AND  packages[0].version

# 2. tag and push
git tag v0.3.3 && git push origin v0.3.3

该标签会触发 .github/workflows/release.yml，此工作流会验证版本号一致、构建、通过 Trusted Publishing 发布到 PyPI，然后在 MCP registry 中登记此次发布。这两个步骤都不存储令牌：PyPI 使用来自此仓库和 pypi 环境的 OIDC，而 registry 使用 GitHub OIDC。首次发布前，两者都需要进行一次性设置：

• PyPI： 在 https://pypi.org/manage/account/publishing/ 为仓库 deBilla/bigquery-mcp 添加可信发布者，工作流为 release.yml，环境为 pypi。
• GitHub： 在仓库设置中创建 pypi 环境。

CI 检查内容

.github/workflows/ci.yml 会在每次推送和拉取请求时运行：

作业	检查内容
test	在 Python 3.11、3.12 和 3.13 上运行测试套件——运行器上不提供 GCP 凭据，这正是设计目的
safety	跟踪的文件中没有凭据格式的字符串；.env/.mcp.json 未跟踪；src/ 中任何位置都没有会修改数据的 BigQuery 客户端调用
package	构建软件包，运行 twine check，断言本地配置未泄漏到 sdist 中，然后将 wheel 安装到干净的 venv，并运行实际协议——5 个工具，每个都标注为只读并附有文档，指令保持完整

最后一项很重要：它能捕获一种情况，即软件包可以顺利安装，却在首次请求时崩溃；这是单元测试无法发现的问题。

许可证

MIT——请参阅 LICENSE。