Summary

Cheap to explore, hard to run up a bill.

Two decisions define this server: the metadata is cached and searchable, so finding the right table costs nothing, and every query path is bounded — an automatic LIMIT on the interactive tool, a scan ceiling on both, and a dry-run scan estimate you can call first. The export tool drops the LIMIT when you genuinely need every row, and keeps the ceiling.

What it is

A BigQuery server that caches dataset, table and column metadata locally and serves it over MCP, so a model can learn the shape of a warehouse before it queries it — and then query it under a cost ceiling. Package bq_mcp_server, version 0.2.2.

What you get

`get_datasets` and `get_tables` for the inventory, the latter scoped to one dataset and optionally one project
`search_metadata` — keyword search across datasets, tables and columns in the local cache, which is how a model finds the right table without listing everything
`execute_query` — SQL execution that inserts a LIMIT clause for you and refuses queries that would scan too much
`check_query_scan_amount` — the scan size of a query before you run it
`save_query_result` — the export path: results written to a local file as CSV or JSONL, with no automatic LIMIT, still bounded by the scan ceiling and with path validation against directory traversal

Requirements

Python 3.11 or later, a Google Cloud project with the BigQuery API enabled, and credentials — Application Default Credentials by default, or a service-account JSON file named in `GCP_SERVICE_ACCOUNT_KEY_PATH`. `PROJECT_IDS` is the one required setting, a comma-separated list, and it can be passed as the --project-ids argument instead; command-line arguments win over the environment. Run it with uvx straight from the repository, or install the package with uv or pip. The knobs that matter for cost and freshness are `MAX_SCAN_BYTES`, which defaults to 1GB, `QUERY_TIMEOUT_SECONDS` at 300, `DEFAULT_QUERY_LIMIT`, and `CACHE_TTL_SECONDS`, which defaults to 3600; `DATASET_FILTERS` narrows what gets cached at all. Transport is stdio.

Setup effort

One command plus a key — pip install bq_mcp_server, then supply credentials