dry_run_query
Perform a dry run of a BigQuery query to check if it's valid and estimate its size
LABSCO SUMMARY
Two guardrails that matter on BigQuery: no writes, and no runaway scans.
A general SQL tool on BigQuery risks two expensive mistakes — a modifying statement and a query that scans a fortune. Both are refused here at the tool boundary rather than left to prompting, which is why this is a narrower and safer thing to hand an agent than a generic client. The trade is real: you cannot write, and a legitimately large analytical query will be blocked.
What it is
A BigQuery query runner with a validation step built into the contract. It can estimate a query's processing size without running it, and its execution tool refuses data-modifying statements and anything that would scan more than 1TB.
What you get
- A dry run that validates the query and estimates how much data it will process, checked against the 1TB limit —
dry_run_query - Query execution that rejects DML statements and over-limit scans before running, and returns results as structured JSON —
run_query_with_validation
Requirements
Google Cloud authentication, either gcloud auth application-default login or a service account key path in GOOGLE_APPLICATION_CREDENTIALS. Node.js v16 or higher. Runs as a Node process against the built build/index.js. The package is bigquery-analysis-mcp-server 0.1.0.
Setup effort
One command plus credentials — npx -y github:gotalab/bigquery-analysis-mcp-server, then supply credentials
USE CASES
01
Finding out what a query will cost before you run it
Dry-run it and read the estimated processing size, which is what the bill is based on, then decide whether to narrow the range.
02
Letting an agent explore a warehouse without risk of writes
Give it only this server: modifying statements are rejected by the tool, so the worst outcome is a refused query rather than changed data.
03
Answering an ad-hoc analytics question in the conversation
Validate the SQL, then execute it and get the rows back as JSON ready for the next step of the analysis.
2 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
run_query_with_validation
Run a BigQuery query with dry run validation (fails if query exceeds 1 TB or contains DML statements)
BEFORE YOU INSTALL
What to know first
Tools you get
2 tools when we connected. run_query_with_validation rejects DML statements, and both tools refuse queries whose dry run estimates more than 1TB of processing.
Requires
- npx on PATH
- Node.js v16 or higher
- GOOGLE_APPLICATION_CREDENTIALS in your environment
Where it runs
The documented client runs the server on your machine.
CONTEXT COST
Light Standing cost
Rated by the size of the 2 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
Build from source
TERMINAL
git clone https://github.com/gotalab/bigquery-analysis-mcp-server
cd bigquery-analysis-mcp-server
npm install
npm run buildnpx
TERMINAL
npx -y github:gotalab/bigquery-analysis-mcp-serverMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"bigquery": {
"command": "node",
"args": [
"<YOUR_PATH_TO_BIGQUERY_SERVER>/build/index.js"
]
}
}
}This block runs the build from the steps above: <YOUR_PATH_TO_BIGQUERY_SERVER> is the full path to your bigquery-analysis-mcp-server clone. Authenticate first with gcloud auth application-default login, or export GOOGLE_APPLICATION_CREDENTIALS pointing at a service-account key file.
The configuration on this page does not set GOOGLE_APPLICATION_CREDENTIALS; the project's instructions set it with an export line. That line reaches only programs started from the same terminal, so to supply GOOGLE_APPLICATION_CREDENTIALS, start your client or the server from that terminal.
