BigQuery Data Platform

BigQuery MCP

A read-only Model Context Protocol server over Google BigQuery. It lets an AI client (Claude Code, Claude Desktop, …) answer plain-language data questions by discovering schema and running SELECT queries.

The AI does the natural-language → SQL translation; this server just safely executes against BigQuery under your own Google credentials.

• Docs: https://debilla.github.io/bigquery-mcp/
• Repo: https://github.com/deBilla/bigquery-mcp
• PyPI: data-platform-mcp
• MCP registry: mcp-name: io.github.deBilla/data-platform-mcp

Tools exposed

Only run_query costs anything, so the discovery tools are the ones to spend first. Two of them exist to prevent specific, repeated mistakes:

• `get_table_schema` reports partitioning from table metadata, never from column names. A table with a partition_date column may not be partitioned — in which case no WHERE clause reduces the scan and every query reads the whole table. The response flags this explicitly when the table is large.
• `check_table_freshness` finds tables that stopped being written to without being dropped. Those return stale data rather than an error, which is the failure mode nobody notices.
• `find_code_assets_using_table` answers the other half. The scheduled-query tools say what *writes* a table; this says who *reads* it, which is the question before a schema change. It is also the one discovery tool that is not free: it opens every asset it considers, spending Dataform read quota, so it is capped and reports how much of the project it actually covered. A result is evidence about the assets scanned, never proof that nothing else uses the table — assets it could not read are listed separately rather than counted as misses.
• `list_scheduled_queries` says why. A stale table is usually a scheduled query that was disabled or is failing, and that lives in a different API (BigQuery Data Transfer) needing roles/bigquerydatatransfer.viewer. Without that role the two tools return an error naming it and everything else works normally. Most scheduled queries declare no destination because they write with DDL, so the target is read out of the SQL and reported as writes_to_from_sql — a heuristic, labelled as one.

BigQuery Studio notebooks and saved queries

These are not BigQuery resources. BigQuery Studio stores each code asset as a Dataform repository holding a single file, which means a third API and a third permission — roles/dataform.viewer — beyond BigQuery and the Data Transfer Service. Without it the three tools return an error naming the role and everything else works normally. They are also invisible in the Dataform UI, so nothing in the console hints that this is where they live.

Two things about that storage are worth knowing before you configure it:

• Code assets are regional, and it is not the dataset region. Dataform rejects multi-regions, so a platform whose datasets are US keeps its notebooks in something like us-central1. No configuration is needed: when location is a multi-region the server probes the regions inside it, uses the one holding the assets, and says so — a multi-region cannot simply be inherited, because using it is guaranteed to fail rather than merely likely to. Pin code_asset_location (or BQ_CODE_ASSET_LOCATION) to skip the probing; an explicit value is never second-guessed, so a wrong one returns an empty list rather than an error. Every result echoes back the location it read.

• Notebook bodies are mostly output. Across 52 real notebooks, cell outputs were 77% of the bytes — one was 1.44 MB of file for 80 KB of code. Outputs are stripped before anything is returned, and the saving is reported so you can see that what is missing was rendered charts rather than logic.

Reads are quota-limited by volume rather than by concurrency, and the quota refills over tens of seconds. Exhaustion is retried with backoff and, if it persists, reported as something to retry shortly rather than as a failure.

Scheduled Colab notebooks

A notebook in BigQuery Studio can have a schedule attached to it, and those runs are where scheduled work goes unwatched: nothing reports on them, so a notebook can fail nightly for weeks and the only symptom is a table that quietly stopped moving. On the platform this was built against, 354 of 7,061 runs had failed and none of it was visible.

Answering one question means joining three resources, which is most of why it was hard to see. The schedule is a Vertex AI Schedule (cron, timezone, paused or not); each run is a NotebookExecutionJob; the notebook is the same Dataform code asset list_code_assets lists — so a failing schedule leads straight to get_code_asset for the code that failed. That means a fourth API and a fourth permission, roles/aiplatform.viewer. Without it the three tools return an error naming the role and everything else works normally. No new dependency: this talks to Vertex AI over REST rather than pulling in google-cloud-aiplatform for two list endpoints.

Three things are worth knowing before trusting what you see:

• A schedule reports itself healthy while its notebook fails. Every one of 49 live schedules reports its last scheduled run as OK — including one whose previous 79 runs had failed. OK means the scheduler successfully *launched* a job, not that the notebook ran. That field is what the console shows first, and it is exactly how this went unnoticed, so health here is always computed from execution jobs and the schedule's own status is never reported as one. A PAUSED schedule, meanwhile, is the single most common reason a notebook-written table went stale.

• Outcome cannot be filtered server-side. Vertex AI rejects a jobState filter outright and caps pages at 100, so "show me the failures" means reading pages and filtering locally. Runs *are* ordered newest-first, which is what makes a bounded window affordable: lookback_days (30 by default, so monthly schedules show at least one run) stops the walk instead of scanning a year of history. 30 days is about 7 API calls; 90 is about 23.

• Runs outlive the schedule that created them. Deleting and recreating a schedule is the normal way to edit one, so 7,061 live runs referenced 75 distinct schedules of which only 49 still existed. Those runs are real and their failures count, so they are labelled (schedule no longer exists) rather than dropped. For the same reason display names are not unique — two live schedules shared one — so an ambiguous name is an error listing the candidates and their ids, never a silently chosen first match.

data-platform-mcp doctor reports how many schedules are readable, how many are paused and how many failed in the last week.

Environments

One server answers questions about several targets — a warehouse and its staging copy, or two regions of the same project. Every tool takes an optional environment; omitting it uses the default.

# ~/.config/data-platform-mcp/config.toml

default_environment = "warehouse"

[environments.warehouse] project = "my-data-platform" impersonate = "data-platform-mcp-ro@my-data-platform.iam.gserviceaccount.com" dataset_allowlist = ["sales", "events"]

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

See config.toml.example for every setting, or set BQ_MCP_ENVIRONMENTS to the same structure as JSON. A single `BQ_PROJECT` still works unchanged — it becomes one environment named default.

An environment can be named by its own name, an alias, the built-in shorthands (prod, stg, dev, live) or its project id. An unknown name is an error naming the valid options, never a silent fall back to the default: a typo that answered a production question from staging would be invisible in the reply. Every result echoes back the environment it came from.

Regions are why this matters most here. BigQuery cannot query across locations, and its error for trying names neither location, so it reads as a missing table. One environment per location; doctor reports which datasets are where.

Read-only as a property of the identity

The SELECT-only guard and the readOnlyHint annotations are promises about this code. Pointing the server at a service account that holds only roles/bigquery.jobUser and a dataset-scoped roles/bigquery.dataViewer makes it a fact about the credentials — enforced by IAM whatever the code does, and whatever your own roles allow:

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

Creates the account, grants those two roles, and gives you roles/iam.serviceAccountTokenCreator on it so the server can impersonate it. Add --dry-run to see the commands first; it is safe to re-run.

With --datasets, the dataset allowlist stops being an if statement in this process and becomes a grant Google enforces.

macOS setup

Terminal.app is not Xcode. It ships with every Mac. What does *not* ship is the Xcode Command Line Tools, and an analyst's laptop usually has neither those nor Homebrew. Nothing here needs them — but it is easy to trip over by accident, because git, make, clang and the stock /usr/bin/python3 are stubs for that bundle: running any of them pops a system dialog offering to install about a gigabyte of developer tooling.

None of the commands below invoke one. They use only utilities macOS already has — curl, tar, sh, uname — because both installs are self-contained:

The whole terminal requirement is the three blocks below, once.

1. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

which uvx # note this absolute path — Claude Desktop will need it

Typically /Users/ /.local/bin/uvx.

2. Install the Google Cloud CLI

Pick the build for your chip — uname -m prints arm64 for Apple Silicon, x86_64 for Intel:

# Apple Silicon

cu