BigQuery MCP Server
Connect AI agents to Google BigQuery — run SQL, explore datasets, and inspect schemas over MCP.
Updated
What is BigQuery MCP?
The BigQuery MCP server is a Model Context Protocol server that lets AI agents query and explore Google BigQuery — running SQL, listing datasets and tables, and inspecting schemas — through a standardized tool interface.
It is a fully managed, remote server hosted by Google at https://bigquery.googleapis.com/mcp. There is nothing to install or run yourself: the endpoint is enabled with the BigQuery API and runs on Google's infrastructure. Agents authenticate with OAuth 2.0 using Google Cloud identities (the server does not accept API keys), scoped to https://www.googleapis.com/auth/bigquery and gated by IAM roles such as BigQuery Job User and BigQuery Data Viewer.
Because it speaks MCP, any compatible client — Claude, Cursor, Gemini CLI, or a custom agent — can connect to it and treat your data warehouse as a set of callable tools. Read-only and read-write query tools are available, with query timeouts and row caps applied server-side for safety.
Tools the BigQuery MCP server exposes
| Tool | What it does |
|---|---|
| execute_sql | Run a SQL query against BigQuery (read-write; supports DML/DDL). |
| execute_sql_readonly | Run a read-only SQL query; blocks DML, DDL, and Python UDFs. |
| list_dataset_ids | List the dataset IDs available in the project. |
| list_table_ids | List the table IDs within a given dataset. |
| get_dataset_info | Return metadata for a specified dataset. |
| get_table_info | Return schema and metadata for a specified table. |
Connect the BigQuery MCP server
Claude Code
- 1
Enable the BigQuery API
In your Google Cloud project, enable the BigQuery API and grant your identity roles/bigquery.jobUser, roles/bigquery.dataViewer, and roles/mcp.toolUser.
- 2
Add the remote MCP server
Register the HTTP endpoint https://bigquery.googleapis.com/mcp with Claude Code as an MCP server.
- 3
Authenticate with OAuth
Complete the Google OAuth 2.0 flow with scope https://www.googleapis.com/auth/bigquery (API keys are not accepted).
- 4
Verify the tools
Confirm the BigQuery tools (e.g. list_dataset_ids, execute_sql_readonly) appear, then ask Claude to list your datasets.
Requires a Google Cloud project with the BigQuery API enabled and an identity holding the BigQuery + MCP Tool User IAM roles.
Cursor
- 1
Open MCP settings
In Cursor, go to Settings and open the MCP / Tools configuration.
- 2
Add the BigQuery server
Add a remote MCP server pointing to the HTTP URL https://bigquery.googleapis.com/mcp.
- 3
Sign in with Google
Authorize via OAuth 2.0 using Google Cloud credentials with the https://www.googleapis.com/auth/bigquery scope.
- 4
Test a query
Reload Cursor, confirm the BigQuery tools are available, and prompt the agent to run a simple read-only query.
Same Google Cloud prerequisites: BigQuery API enabled and an identity with the required IAM roles.
Sample use cases
An analyst agent answers ad-hoc data questions in plain English
The agent translates the question to SQL, runs a read-only query, and returns the result without anyone writing SQL by hand.
A scheduled workflow monitors a metrics table for anomalies
A nightly Gamut agent queries the table, summarizes outliers, and posts a digest to chat.
A webhook-triggered agent enriches incoming events
The agent looks up matching records in BigQuery to add context before downstream steps run.
Security & permissions
Authentication is OAuth 2.0 with Google Cloud identities (not API keys), scoped to https://www.googleapis.com/auth/bigquery. Access is governed by IAM: the connected identity needs roles such as MCP Tool User (roles/mcp.toolUser), BigQuery Job User (roles/bigquery.jobUser), and BigQuery Data Viewer (roles/bigquery.dataViewer). The agent can only see and query the datasets those roles permit. Server-side guards apply — a read-only query tool blocks DML/DDL, query timeouts auto-cancel long jobs, and result rows are capped — limiting how much data any single call can touch. Grant least-privilege roles and a dedicated identity to keep the agent's scope tight.
Using BigQuery MCP with Gamut
In Gamut, you add the BigQuery MCP server as a tool on an agent and Gamut manages the OAuth connection to your Google Cloud project. An event- or schedule-triggered workflow can then have the agent run SQL and read schemas without a human in the loop — for example, a nightly job that queries a metrics table, summarizes anomalies, and posts the result to chat, or a webhook-triggered agent that looks up a record in a dataset to enrich an incoming event. The agent only has the BigQuery access granted by the IAM roles on the connected identity, so its reach is bounded by the datasets and roles you assign.
Frequently asked questions
What is the BigQuery MCP server?
It is Google's fully managed, remote Model Context Protocol server for BigQuery, hosted at https://bigquery.googleapis.com/mcp. It lets AI agents run SQL queries and explore datasets, tables, and schemas in your BigQuery project through standard MCP tools.
Is the BigQuery MCP server free?
There is no separate charge for the MCP server itself — you pay standard BigQuery pricing for the queries it runs (bytes processed) and storage. A BigQuery sandbox provides a no-billing way to test, and Google Cloud includes a free monthly query and storage allowance.
Is the BigQuery MCP server hosted or self-hosted?
Hosted. Google runs it as a fully managed remote endpoint enabled with the BigQuery API — there is no local server to install or maintain. (Community self-hosted BigQuery MCP servers exist on GitHub, but the official one is Google-hosted.)
How do I connect the BigQuery MCP server to Claude or Cursor?
Add the remote server URL https://bigquery.googleapis.com/mcp in your client's MCP settings, then authenticate with Google OAuth 2.0 using a Cloud identity that has the BigQuery and MCP Tool User IAM roles. API keys are not accepted; the required scope is https://www.googleapis.com/auth/bigquery.