bigquery-mcp

# BigQuery MCP

[![CI](https://github.com/deBilla/bigquery-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/deBilla/bigquery-mcp/actions/workflows/ci.yml)

A **read-only** [Model Context Protocol](https://modelcontextprotocol.io) 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`](https://pypi.org/project/data-platform-mcp/)
- **MCP registry:** mcp-name: io.github.deBilla/data-platform-mcp

---

## Tools exposed

| Tool | Purpose | Cost |
|------|---------|------|
| `list_datasets` | List datasets in the project | free |
| `list_tables` | List tables/views in a dataset | free |
| `get_table_schema` | Columns (nested paths expanded), **partitioning**, size, row count | free |
| `check_table_freshness` | When each table was last written — catches stale sources | free |
| `list_environments` | Which BigQuery environments are configured, and the default | free |
| `run_query` | Run a validated, read-only `SELECT` and return rows | scans data |

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.

---

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

```toml
# ~/.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`](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:

```bash
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:

| Install | Why it needs nothing else |
| --- | --- |
| `uv` | A standalone binary. Its installer never mentions Python, and it downloads its own to run the server. |
| Google Cloud CLI | The macOS tarball bundles its own Python (`.install/bundled-python3-unix-darwin-*`). |

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

### 1. Install uv

```bash
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:

```bash
# 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

```bash
./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

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

Then register with your client: [Claude Desktop](#claude-desktop) or
[Claude Code](#4-register-with-your-ai-client).

### 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.)

```bash
# 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:

```json
{
  "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:

```bash
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](#4-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
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

This installs `uv.exe` and `uvx.exe` into `%USERPROFILE%\.local\bin`. Confirm
the exact path, because the Desktop config needs it in full:

```powershell
(Get-Command uvx).Source
```

### 2. Install the Google Cloud CLI

Download and run
[GoogleCloudSDKInstaller.exe](https://dl.google.com/dl/cloudsdk/channels/rapid/GoogleCloudSDKInstaller.exe).
Leave **"Bundled Python"** ticked — it is what lets the SDK run without a
separate Python install, the same property the macOS tarball has.

### 3. Authenticate

In a **new** PowerShell window, so it picks up the updated `PATH`:

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

This writes credentials to
`%APPDATA%\gcloud\application_default_credentials.json`, which the Google
libraries r