BigQuery MCP

BigQuery MCP is a free MCP server that gives your AI agent four tools for BigQuery. Your agent can list datasets and tables, read a table’s schema, and run SQL, with two guards built in: only SELECT statements run, and a query that would scan more than your byte limit is refused before it costs anything. It is its own VS Code extension, it runs on your machine, and it uses your own Google account.

There is no server to host and no config file to edit. You install the extension, sign in to Google once, and the tools appear in every agent it finds: VS Code Copilot, Claude Code, Cursor, OpenAI Codex, Google Gemini, Windsurf, Continue.dev, and Cline.

What you can ask

  • “Which datasets are in this project?”
  • “What columns does the events table have?”
  • “How many orders were placed each day last week?”
  • “Show the top ten pages by sessions from the GA4 export”
  • “How much data would this query scan?”
  • “Which tables in this dataset are largest?”

The four BigQuery MCP tools

Tool What it does What you can pass
bq_list_datasets List the datasets in a project A project, or your default
bq_list_tables List the tables and views in a dataset The dataset
bq_get_table Get a table’s schema, row count, size, and description Dataset and table
bq_query Run a read-only SQL SELECT The SQL, a location, a dry-run switch, and up to 1,000 rows returned

Three things people use it for

Asking questions of the GA4 export

If Google Analytics exports to BigQuery, ask in plain language and the agent writes the SQL against the events tables. It reads the schema first, so it knows about the nested fields.

Knowing the cost before you run it

Ask how much a query would scan. The dry run returns the bytes without running anything, which is the number BigQuery bills on.

Writing application queries against the real schema

Before the agent writes a query into your code, have it read the table schema. Column names and types come from the table and not from a guess.

Set it up in five steps

A setup wizard opens the first time you launch the extension. OAuth is the usual choice.

  1. Create a project in the Google Cloud Console, or pick one you already have.
  2. Enable the BigQuery API under APIs and Services.
  3. Create an OAuth client ID of type Desktop app.
  4. Paste the client ID and secret into the wizard.
  5. Sign in to Google in the browser window that opens, and authorize.

If your consent screen is set to External, add yourself as a test user first. The wizard also accepts Application Default Credentials from the gcloud CLI and a service account key.

Set bigqueryMcp.projectId to the project that runs your queries. bigqueryMcp.maxBytesBilled is the ceiling for a single query, 1 GB by default. Every query is dry-run first, and one that would go over the ceiling is refused.

Using BigQuery MCP with Claude Code, Cursor and other agents

You do not add a server entry by hand. The extension writes the registration for each agent it finds: ~/.claude.json for Claude Code, ~/.cursor/mcp.json for Cursor, ~/.codex/config.toml for OpenAI Codex, ~/.gemini/settings.json for Gemini, and the matching files for Windsurf, Continue.dev, and Cline. VS Code Copilot picks it up through the VS Code API.

Open a new session in any of them and the tools are in the tool list. To limit which agents get them, switch the others off in VS Code settings under bigqueryMcp.agents. The command “BigQuery MCP: Remove from All Agents” takes every registration back out.

Limits

  • Only a single SELECT statement runs. No inserts, updates, deletes, or table changes.
  • A query over the byte ceiling is refused. Raise the setting if you need to scan more.
  • Results are capped at 1,000 rows per call. Aggregate in SQL for anything larger.
  • Queries are billed to the project you set, at your normal BigQuery rates.

Common questions

Is BigQuery MCP free?

Yes. The extension is free and MIT licensed. Google’s own charges for the API are separate.

Is this Google’s official BigQuery MCP server?

No. Google offers its own managed BigQuery MCP server through Google Cloud. This is an independent, read-only extension with a spending guard, registered across eight agents from one install.

Can the agent run up a large bill?

Each query is dry-run first and refused if it would scan more than the ceiling you set, 1 GB by default.

Can it write to a table?

No. Anything other than a single SELECT is rejected.

Does it work with Claude Code and Cursor?

Yes. Both are registered automatically, along with Copilot and five other agents.

Where does my data go?

Nowhere except Google. The MCP server runs on your own machine and calls Google’s API with your credentials. There is no telemetry, and the sign-in token is kept in VS Code’s encrypted secret storage.

Install it

BigQuery MCP is free and MIT licensed.

Related