Connect BigQuery to Claude Code
Explore datasets and table schemas, price a query with a dry run, then run it. Add Toolspoke to Claude Code once and it can use 10 BigQuery actions. Your BigQuery credential stays in Toolspoke, and you choose which actions Claude Code may call.
Set it up in Claude Code
Three steps, the first one once for every toolkit you will ever add.
Add Toolspoke to Claude Code
Run it in your project, then /mcp to sign in
claude mcp add --transport http toolspoke https://toolspoke.com/mcpThe sign-in opens in your browser, and Toolspoke asks you to approve it.
Install BigQuery and connect it
Add BigQuery to a project in your Toolspoke workspace.
OAuth 2.0. You provide it once, when you install the connector. Toolspoke encrypts it at rest and decrypts it only for the length of a single call, and the gateway attaches it to the outbound request itself, so it is never part of the arguments an agent sends.
- OAuth client ID
- Google Cloud console → APIs & Services → Credentials → OAuth 2.0 Client IDs (Desktop app). Enable the BigQuery API on the same project.
- OAuth client secret
- Shown next to the OAuth client ID in the Google Cloud console.
- OAuth refresh token
- Generate once with the https://www.googleapis.com/auth/bigquery scope and offline access, then paste it here. To keep the install read-only, grant the authorising account BigQuery Data Viewer and Job User and nothing more.
- Default project ID
- The billing project every job runs in and every dataset listing defaults to. A call may name a different project the same credential can reach.
Choose what Claude Code may do
All 10 actions start on. Switch off any of the 2 actions that change something in BigQuery, and Claude Code gets a refusal if it tries.
What you can ask Claude Code for
A few of the BigQuery actions that only read, so they are safe to try first.
- Validate a query and report what it would cost, without running it
- Fetch rows from a query job that has already run, by job id
- List the datasets in a project with their ids, locations and labels
- Fetch one dataset's metadata: description, location, default table expiry, labels and access entries
What Claude Code can do in BigQuery
8 actions read, one writes and one deletes or permanently changes something.
Reads
Dry run query
Validate a query and report what it would cost, without running it. Returns totalBytesProcessed and the resolved schema; no job is created, no slot is used and nothing is billed. Call this before run_query on anything that touches a large table, bytes scanned is what BigQuery charges for, and a missing WHERE on a partitioned table is the difference between megabytes and terabytes. It also catches a wrong column or dataset name for free, so use it instead of a SELECT … LIMIT 1 to check that a query parses.
Get query results
Fetch rows from a query job that has already run, by job id. Use it for the second and later pages of a large result set, and to collect the answer from a run_query call that returned jobComplete false. Reading results again costs nothing, the bytes were billed when the job ran. Job ids come from run_query's jobReference or from list_jobs.
List datasets
List the datasets in a project with their ids, locations and labels. Call this first when you do not know what data the project holds; the datasetId it returns is what list_tables and get_dataset need. Costs nothing.
Get dataset
Fetch one dataset's metadata: description, location, default table expiry, labels and access entries. Use it when a query fails on a location mismatch, or to check who a dataset is shared with. Costs nothing.
List tables
List the tables and views in one dataset, with their type, creation time and partitioning. Call it after list_datasets to find a table id, then get_table for the columns. Costs nothing.
Get table
Fetch one table's full metadata, including the column schema with types, modes and descriptions, the row count, the bytes on disk and the partitioning and clustering fields. This is the call to make before writing any query: it names the columns exactly, and the partitioning field is what tells you the WHERE clause that keeps dry_run_query's byte estimate small. Costs nothing.
List jobs
List recent jobs in a project, newest first, with state, user and error result. Use it to find what is running now, to find the job id of a query somebody else ran, or to see why a scheduled load failed. Set state_filter to "running" to find a job worth cancelling. Costs nothing.
Get job
Fetch one job in full: its configuration, state, timings, error result and query statistics including bytes processed and billed and slot milliseconds. Use it after run_query to find out what a query actually cost, and after a failure to read the error BigQuery recorded. Costs nothing.
Writes
Run query
Run a GoogleSQL query and return the result rows. Classified as a write because jobs.query is the same endpoint for SELECT, INSERT, MERGE and DDL, and the gateway cannot tell which a caller sent, pair it with an IAM role that only reads if this install should only read. Call dry_run_query first on anything unfamiliar: this call is billed on bytes scanned. Keep max_results small and put a LIMIT in the SQL. If the response comes back with jobComplete false, take jobReference.jobId and poll get_query_results.
Deletes or permanently changes
Cancel job
Ask BigQuery to stop a running job. Destructive because it ends work in progress: a load or DML job that was part-way through is abandoned, the bytes already scanned are still billed, and the job cannot be resumed, it has to be submitted again. Confirm the job id and its state with list_jobs or get_job first. Cancellation is a request, so poll get_job to see the job reach DONE.
BigQuery in Claude Code: questions
Does Claude Code see my BigQuery credential?
No. The credential is stored encrypted in Toolspoke, and the gateway adds it to each call. Claude Code only ever talks to Toolspoke, and the dashboard shows the last four characters of the credential and nothing more.
Can I stop Claude Code from changing things in BigQuery?
Yes. Each of the 10 actions can be switched off for a project. Turn off the 2 that change something and Claude Code can only read.
Will 10 actions crowd Claude Code's context?
No. Toolspoke shows Claude Code five bridge tools, plus a guide where a toolkit has one, and Claude Code searches for the BigQuery action it needs when it needs it. Adding more toolkits does not add more tools to its list.
Can I add it once for every project?
Yes. Add --scope user to the command and Claude Code keeps Toolspoke in every project on this machine. Without it, the server is added to the project you ran the command in.
What does it cost?
Tool calls are free on every plan, and a BigQuery call does not run in a sandbox, so it bills nothing.
BigQuery in your other apps
Try BigQuery in Claude Code
Free to start, and tool calls cost nothing on any plan.