At a glance
- Availability: Experimental (how to enable).
- Auth: OAuth 2.0.
- Connection: A user authorizes the connection in the provider’s consent screen.
- Scopes:
https://www.googleapis.com/auth/cloud-platform.read-only. - Optional scopes:
https://www.googleapis.com/auth/bigquery. - Docs: https://cloud.google.com/bigquery/docs/authentication
Credentials
Set these per environment. See Connect an integration. With a managed OAuth app, Connect works without these variables; set them to use your own OAuth app instead.Setup
- Create or reuse a Google Cloud project: Go to https://console.cloud.google.com and create a project (or reuse the one that already hosts your Google OAuth app). Note its project ID - every BigQuery call takes a projectId parameter (the same value you would put in a GOOGLE_CLOUD_PROJECT env var). Without billing enabled you can still use the free BigQuery sandbox to test queries against public datasets.
- Enable the BigQuery API: Open https://console.cloud.google.com/apis/library/bigquery.googleapis.com, select your project, and click Enable.
- Configure the OAuth consent screen and client: Under APIs & Services > Credentials, create (or reuse) an OAuth 2.0 Client ID of type Web application. Add your app’s redirect URI ending in /api/auth/google-bigquery/callback. The same Google OAuth client can be shared across all Google connectors.
- Set environment variables: Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET from the OAuth client you created. These are shared with other Google integrations.
- The default scope is read-only (cloud-platform.read-only): listing datasets/tables and SELECT queries work, but DML (INSERT/UPDATE/DELETE) requires granting the optional full bigquery scope.
- There is no project-wide env var: pass the Google Cloud project ID as the projectId parameter on every call (treat it like GOOGLE_CLOUD_PROJECT).
- Queries are billed to the projectId you pass; use dryRun to estimate bytes processed before running expensive queries.
- The query API defaults to legacy SQL - keep useLegacySql set to false to write GoogleSQL.
Tools
| Tool | Access | Description |
|---|---|---|
| List Projects | Read | List the Google Cloud projects the connected user can access, so agents can discover the projectId every other tool requires |
| List Datasets | Read | List all BigQuery datasets in a Google Cloud project |
| List Tables | Read | List tables and views in a BigQuery dataset |
| Get Table Schema | Read | Get a table’s metadata including its full column schema, row count, and size |
| Preview Table Data | Read | Read sample rows directly from a table without running a query - no bytes are billed, ideal for inspecting data before writing SQL |
| Run SQL Query | Read | Run a read/SELECT GoogleSQL query and return the first page of results. With the default read-only scope only SELECT queries work; DML statements (INSERT/UPDATE/DELETE) require the full https://www.googleapis.com/auth/bigquery scope. |
| Get Query Results | Read | Fetch additional pages of results from a previously started query job, using the jobId and pageToken returned by Run SQL Query |
Example prompts
- List the datasets and tables in my BigQuery project and summarize what data is available.
- Write and run a BigQuery SQL query to answer a question about my data, then explain the results.
- Show me the schema of a BigQuery table and suggest useful queries against it.