Skip to main content
Google BigQuery is a serverless data warehouse for analytics at scale. The BigQuery MCP server lets you explore projects, inspect datasets, and run SQL using natural language.

​
What Can It Do?

  • Discover projects and datasets you have access to
  • Inspect table metadata including schema and row counts
  • Run SQL queries and return structured results
  • Power data workflows by chaining outputs to other tools

​
Where to Use It

Add BigQuery as a tool to any agent. The agent can then query and explore your data conversationally, choosing the right actions based on context. To add an MCP tool to your agent:
  1. Open your agent’s configuration
  2. Click Add tools → Connect an app with MCP
  3. Search for the integration and select it
  4. Authenticate with your account
You can control which tools your agent has access to. After adding an integration, click on it to enable or disable specific tools based on what your agent needs.

​
In Workflows (Via Agent Node)

For automated pipelines, use an Agent Node with BigQuery tools. This gives you the flexibility of an agent within a deterministic workflow.

​
As a Custom MCP Node

You can also create a standalone MCP node for a specific action. This generates a reusable node that performs one task, useful when you need the same operation repeatedly in workflows.
To create a custom MCP node:
  1. Go to your node library and search for the integration
  2. Click Create a node with AI
  3. Describe the specific action you want (e.g., “Run this SQL query on my dataset”)
  4. Test the node and save it for reuse
Custom MCP nodes are single-purpose by design. For tasks that require multiple steps or dynamic decision-making, use an agent instead.

​
Authentication

BigQuery supports two ways to connect your GCP credentials:

Google OAuth (default)

Sign in with your Google account. Quick to set up, but requires re-authentication when your GCP session-control window expires (typically every 1–24 hours, depending on your org’s policy).

Workload Identity Federation

Keyless, token-based access. No daily reconnect, no stored secrets. Best for teams that need always-on BigQuery access without manual re-auth.

​
Setting up Workload Identity Federation (WIF)

WIF lets Gumloop mint short-lived access tokens by federating into your GCP project. There are no static keys or OAuth sessions to manage. To set it up:
  1. Create a workload identity pool and OIDC provider in your GCP project that trusts Gumloop’s issuer (https://api.gumloop.com)
  2. Create a target service account with the BigQuery permissions your team needs
  3. Grant the pool permission to impersonate that service account
  4. In Gumloop, go to your Apps page, click Add Credential, and select BigQuery (Workload Identity)
  5. Enter three values: your GCP Project Number, the Workload Identity Pool Resource Name (this must be the full provider resource path, e.g. projects/123456789012/locations/global/workloadIdentityPools/gumloop-pool/providers/gumloop-oidc), and the Target Service Account Email
Add the WIF credential at the team level so the whole team shares one keyless connection. Use a personal credential if you only need it for your own agents.
For the complete setup walkthrough (including exact gcloud commands), see the BigQuery Workload Identity Federation guide.

​
FAQ

Yes. If you have both a standard BigQuery OAuth credential and a WIF credential, Gumloop will try your OAuth token first. If it’s expired or missing, it will automatically fall back to your WIF credential. You don’t need to choose one or the other.
No. WIF works transparently. Your agents and workflows continue to use BigQuery the same way. The only difference is how Gumloop authenticates behind the scenes.
If your GCP organization enforces short session-control windows (e.g., 1-hour reauth), OAuth credentials require frequent reconnection. WIF eliminates that. It’s also the better choice for teams that prohibit static service-account key files.

​
Available Tools

ToolDescription
List Project IdsList accessible Google Cloud projects
List Dataset IdsList datasets in a project
List Table IdsList tables in a dataset
Get Dataset InfoGet dataset metadata
Get Table InfoGet table schema and row count
Execute SQLRun a SQL query and return results

​
Example Prompts

Use these with your agent or in the Agent Node: Discover projects: 
List all Google Cloud projects I have access to
Explore datasets: 
List all datasets in my analytics project
Run a query: 
Run "SELECT * FROM sales WHERE region = 'West' LIMIT 100"
Get table info: 
Show me the schema and row count for the customers table

​
Troubleshooting

IssueSolution
Agent not finding the right dataSpecify the project ID and dataset explicitly
Action not completingCheck that you’ve authenticated and have BigQuery access
Unexpected resultsThe agent may chain multiple tools (e.g., listing datasets first, then querying). Review the agent’s reasoning to understand its approach.
Tool not availableVerify the tool is enabled in your agent’s MCP configuration
Agents are smart enough to chain multiple API calls together. For example, asking “What tables are in my analytics dataset?” will find the project and dataset first, then list tables. If results seem off, check the agent’s step-by-step reasoning.

​
Need Help?

Use this integration directly in Claude or Cursor. Connect remotely via the BigQuery MCP server using your Gumloop credentials.