Query your BigQuery data with AI — step by step. We'll show you both the manual approach and the faster way with Contextary.
You can absolutely make this work yourself. Here's everything involved.
Create a service account in Google Cloud Console with BigQuery read permissions. You'll need the bigquery.dataViewer and bigquery.jobUser roles at minimum. Navigate the IAM console, create the account, and assign the right roles at the right scope (project-level vs dataset-level).
Generate and download the service account's JSON credentials file. Store it somewhere safe — it contains the private key for your service account. You'll need the path to this file for the next step.
Search for a community MCP server that supports BigQuery. There are a few out there — check if they're actively maintained, support the features you need, and handle errors gracefully. If you can't find one that works, you'll need to build your own using the MCP SDK. Either way, expect some trial and error.
Point the MCP server at your credentials file, configure the project ID and default dataset, and set up Claude to use it. Debug connection issues, authentication errors, and API quota limits until it works. Each MCP server has its own configuration format, so consult its (hopefully existing) documentation.
Even with an MCP server handling query execution, Claude still doesn't know what your data means. Write a system prompt explaining every table, column, relationship, and business rule. For BigQuery projects with multiple datasets, this gets long fast — and BigQuery's nested/repeated fields add extra complexity to explain.
Every time someone adds a table, renames a column, or changes a business rule, you need to update your system prompt. Forget, and Claude will reference columns that no longer exist or use metric definitions that are out of date. BigQuery schemas tend to change frequently as new data sources are added.
Even with good prompting, Claude will sometimes pick the wrong join key, calculate metrics differently than your team expects, or include records it should filter out. You'll need to review the SQL carefully every time, especially for BigQuery-specific syntax like UNNEST, partitioned tables, and STRUCT fields.
When the SQL is wrong (and it will be), you'll need to figure out where Claude went wrong, correct it, and re-prompt. Over time you'll build up a library of corrections in your system prompt — which makes it longer, which makes it harder to maintain, which brings you back to step 6.
But you'll spend more time managing prompts and copying SQL than actually getting answers. And every person on your team has to set this up independently.
Same result, fraction of the effort. Here's the entire setup.
Enter your GCP project ID and authenticate. Contextary handles the BigQuery connection, discovers your datasets and tables, and maps all your columns — including nested and repeated fields — automatically.
Every dataset, table, column, and data type is cataloged automatically. Contextary understands BigQuery-specific types like STRUCT, ARRAY, and partitioned tables out of the box.
Document metric definitions, gotchas, and business rules. AI suggests annotations based on your schema — you confirm or tweak. Define "active user" once, and every AI tool uses that exact definition.
One config line connects Claude to Contextary via MCP. Claude now has your full schema context and can run queries directly against BigQuery — no separate MCP server to find, configure, or maintain.
Ask Claude anything about your BigQuery data. Contextary provides the context, Claude writes accurate SQL with proper BigQuery syntax, Contextary tells your warehouse what query to run, and you get the answer. No GCP console, no copy-pasting, no SQL review.
When someone adds a gotcha or updates a metric definition, every AI tool sees it immediately. No prompt maintenance, no context window limits, no re-explaining.
| Without Contextary | With Contextary | |
|---|---|---|
| Setup time | Hours of prompt engineering | 60 seconds |
| Schema changes | Manual prompt updates | Auto-discovered |
| Business rules | Copy-pasted into prompts | Documented once, shared everywhere |
| Team consistency | Everyone writes their own prompt | One source of truth |
| Metric definitions | Explained each time | Defined with exact formulas |
| Query execution | Copy-paste between tools | Contextary runs it for you |
| Maintenance | Ongoing prompt management | Set it and forget it |
Connect BigQuery to Claude in 60 seconds. Free to get started.