BQ Agent Gateway

A read-only MCP server that connects Claude to BigQuery with layered guardrails against dangerous and expensive SQL.

What it blocks

Static AST validation (parsed with sqlglot, not regex):

• Anything that isn't a SELECT (no INSERT/UPDATE/DELETE/MERGE/DDL)

• SELECT * and table.* (but COUNT(*) is fine)

• CROSS JOIN and implicit cartesian products (comma joins with no ON)

• Multiple statements in one call (blocks SELECT 1; DROP TABLE ...)

• Queries referencing datasets outside an allowlist

• Missing LIMIT (auto-injected by default) and over-large LIMITs

BigQuery cost gate:

• A dry-run estimates bytes scanned before running; over-threshold queries are rejected

• Execution sets maximum_bytes_billed as a hard server-side cap, so even a mis-estimate can't overspend — BigQuery kills the job instead

• Row count and wall-clock timeout are capped

Related MCP server: bigquery-mcp-data-agent

Tools exposed

list_datasets, list_tables, describe_table, estimate_query_cost, run_query.

Setup

pip install -r requirements.txt        # or: uv pip install -r requirements.txt
cp .env.example .env                    # then edit values

# Auth: either set GOOGLE_APPLICATION_CREDENTIALS to a service-account key,
# or run:
gcloud auth application-default login

Give the service account only what it needs: roles/bigquery.dataViewer + roles/bigquery.jobUser. The dataViewer role cannot mutate data, so the read-only guarantee is enforced at the IAM layer too, not just in code.

Run

# stdio (for Claude Desktop)
python server.py

# or HTTP
fastmcp run server.py --transport http --port 8000

Register with Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "bq-agent-gateway": {
      "command": "python",
      "args": ["/absolute/path/to/bq-agent-gateway/server.py"],
      "env": {
        "BQ_PROJECT": "my-gcp-project",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/key.json",
        "BQ_ALLOWED_DATASETS": "analytics,prod_reporting",
        "BQ_MAX_BYTES_SCANNED_GIB": "5"
      }
    }
  }
}

Restart Claude Desktop; the BigQuery tools appear in the tools menu.

Design notes / defense in depth

The guardrails are structured as independent layers so a bypass of one doesn't defeat the rest:

1. IAM — read-only service account can't write regardless of SQL.

2. AST validation — shape checks that regex can't do reliably.

3. Dry-run cost gate — the real budget protection for BigQuery.

4. maximum_bytes_billed — hard cap enforced by BigQuery itself.

5. Row/time caps — bound the response size and latency.

Toggle any static rule via env vars (see .env.example) without touching code.