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.
• 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.

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/<you>/.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
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

Avoid brew install --cask google-cloud-sdk: Homebrew itself requires the Command Line Tools, which is the thing this section exists to avoid.

3. Authenticate

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

This writes a credentials file that the Google libraries read directly. gcloud does not need to be on your PATH afterwards — it is needed once, here. That is why a GUI-launched Claude Desktop can query BigQuery even though it cannot see your shell.

Your account needs BigQuery Job User on the project the query runs in, and BigQuery Data Viewer on each dataset it reads — often a different project.

4. Check it worked

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

Then register with your client: Claude Desktop or Claude Code.

Alternative: no terminal at all for the analyst

If even that is too much, an admin can do the credential half centrally and the analyst installs nothing but uv — skipping step 2 and step 3 entirely. (Nothing about this is macOS-specific; it works the same on any OS.)

# 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 data-platform-mcp-ro@your-gcp-project.iam.gserviceaccount.com

The analyst saves that file and points the config at it:

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

The trade-off is real and worth stating. A key file is a long-lived credential sitting on a laptop, where gcloud auth application-default login issues short-lived tokens tied to a person. It is defensible here because the account created by setup --datasets can only read the datasets you name, and because a key can be revoked centrally the moment a laptop is lost — but it is strictly weaker, and it is a per-analyst secret, so do not put it in a shared config file or a repository.

Linux

The same two installs, with no equivalent of the Command Line Tools problem:

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

Then check it worked and register with your client.

Windows

Not verified end to end. The download URLs and install locations below were checked; the flow itself has not been run on a Windows machine. CI tests Linux only. Treat this as a careful derivation, not a tested recipe — and please open an issue if a step is wrong.

1. Install uv

In PowerShell:

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