get_datasetsLABSCO 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_datasetsandget_tablesfor the inventory, the latter scoped to one dataset and optionally one projectsearch_metadata— keyword search across datasets, tables and columns in the local cache, which is how a model finds the right table without listing everythingexecute_query— SQL execution that inserts a LIMIT clause for you and refuses queries that would scan too muchcheck_query_scan_amount— the scan size of a query before you run itsave_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 credentials — pip install bq_mcp_server, then supply credentials
USE CASES
01
Finding the right table in an unfamiliar warehouse
Search the cached metadata by keyword across datasets, tables and columns, then list what else lives in that dataset.
02
Checking what a query will cost before running it
Get the scan amount for the SQL as written, adjust the filter, and only then execute.
03
Exporting a full result set for something downstream
Write the rows to a local CSV or JSONL file without a LIMIT clause, still inside the scan ceiling.
6 tools
Listed in project docs. Your client may show a different list.
get_tablessearch_metadataexecute_querycheck_query_scan_amountsave_query_resultBEFORE YOU INSTALL
What to know first
Tools you get
6 tools named in the project's documentation.
Requires
- pip on PATH
- Python 3.11 or later
- Google Cloud credentials: Application Default Credentials, or a service-account JSON file named in GCP_SERVICE_ACCOUNT_KEY_PATH
- Your GCP project IDs, comma-separated, for --project-ids (or PROJECT_IDS)
INSTALLATION
Connect your client
Add the block to your client, or run the command directly.
Server setup
Configuration file
JSON
{
"mcpServers": {
"bq_mcp_server": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/takada-at/bq_mcp_server",
"bq_mcp_server",
"--project-ids",
"<YOUR_PROJECT_IDS>"
]
}
}
}pip
TERMINAL
pip install bq_mcp_server
