BigQuery MCP
BigQuery MCP server for Claude Code, Cursor, Copilot and five more AI agents. Connect BigQuery to Claude, Copilot, Cursor, Codex, Gemini, Windsurf, Continue.dev and Cline. One extension, 8 agents, no config files to edit.
Install. Sign in with Google. Ask your AI agent about BigQuery.
Quick Start
- Install from the VS Code Marketplace or Open VSX
- Authenticate: the setup wizard appears on first launch
- Ask your AI agent anything about BigQuery
"List the datasets in my project"
"Show the schema of analytics.events"
"How many orders did we get per day last week?"
Prerequisites
You need one of these (the wizard will guide you):
| Method |
Best For |
What You Need |
| OAuth (recommended) |
Personal Google accounts |
A Google Cloud project with OAuth credentials |
| ADC |
Developers with gcloud CLI |
Run one terminal command |
| Service Account |
Workspace admins and servers |
A JSON key file |
Option A: OAuth 2.0 (Browser Login), recommended
- Go to Google Cloud Console
- Create a project (or select an existing one)
- Enable the BigQuery API under APIs & Services > Library
- Create OAuth credentials:
- Go to APIs & Services > Credentials
- Click Create Credentials > OAuth client ID
- Application type: Desktop app
- Copy the Client ID and Client Secret
- Configure the OAuth consent screen (if prompted) and add yourself as a test user
- In the extension wizard, select "OAuth" and paste your Client ID and Secret
- A browser window opens: sign in with your Google account and authorize
Option B: Application Default Credentials
gcloud auth application-default login \
--scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/bigquery
Option C: Service Account Key
- Create a service account in Google Cloud Console and give it access to your BigQuery data
- Download the JSON key file
- In the extension wizard, select "Service Account" and pick the file
Set bigqueryMcp.projectId to the project that runs your queries. bq_query runs only SELECT statements and dry-runs each one first; a query that would scan more than bigqueryMcp.maxBytesBilled (1 GB by default) is refused instead of billed.
| Tool |
What It Does |
Example Prompt |
bq_list_datasets |
Datasets in a project |
"List my datasets" |
bq_list_tables |
Tables and views in a dataset |
"What tables are in analytics?" |
bq_get_table |
Schema, row count and size |
"Show the schema of analytics.events" |
bq_query |
Run a SELECT, after a dry-run cost check |
"Orders per day last week" |
Safety
BigQuery MCP runs SELECT queries only, with a byte limit. Every query is dry-run first. Anything other than a single SELECT, or a query that would scan more than bigqueryMcp.maxBytesBilled (1 GB by default), is refused before it runs or bills.
Supported AI Agents
The extension auto-registers with every AI agent it detects:
| Agent |
How It Registers |
Config File |
| VS Code Copilot |
VS Code API (automatic) |
-- |
| Claude Code |
~/.claude.json |
JSON |
| Cursor |
~/.cursor/mcp.json |
JSON |
| OpenAI Codex |
~/.codex/config.toml |
TOML |
| Google Gemini |
~/.gemini/settings.json |
JSON |
| Windsurf |
~/.codeium/windsurf/mcp_config.json |
JSON |
| Continue.dev |
~/.continue/config.yaml |
YAML |
| Cline |
VS Code globalStorage |
JSON |
You can toggle individual agents on/off in Settings > search bigqueryMcp.agents.
Settings
| Setting |
Default |
Description |
bigqueryMcp.authMethod |
"oauth" |
Auth method: oauth, adc, serviceAccount |
bigqueryMcp.projectId |
"" |
Google Cloud project ID used when a tool call does not name one. |
bigqueryMcp.maxBytesBilled |
1000000000 |
Largest number of bytes a query may bill (default 1 GB). Queries above it fail instead of running. |
bigqueryMcp.agents.* |
true |
Per-agent registration toggles |
bigqueryMcp.registrationScope |
"global" |
Global or workspace registration |
bigqueryMcp.autoStart |
true |
Auto-start server on VS Code launch |
bigqueryMcp.serverLogLevel |
"info" |
Server log verbosity |
Commands
Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and search for:
| Command |
What It Does |
BigQuery MCP: Setup Authentication |
Run the setup wizard |
BigQuery MCP: Register with AI Agents |
Re-register with all detected agents |
BigQuery MCP: Show Status |
Show auth method and server state |
BigQuery MCP: Restart MCP Server |
Restart the background MCP server |
BigQuery MCP: Check Authentication Status |
Verify credentials are valid |
BigQuery MCP: View Server Logs |
Open the output channel for debugging |
BigQuery MCP: Remove from All Agents |
Clean up all agent registrations |
Troubleshooting
"BigQuery MCP: Setup" in the status bar
Your credentials aren't configured. Click the status bar item or run BigQuery MCP: Setup Authentication.
"Permission Denied" errors
Your credentials don't have access to the requested data. Make sure the BigQuery API are enabled in your Google Cloud project.
Server keeps crashing
Run BigQuery MCP: View Server Logs to see the error. Common causes:
- Expired credentials: run the setup wizard again
- Node.js not found: install Node.js 22 or newer
Uninstalling cleanly
Before uninstalling, run BigQuery MCP: Remove from All Agents to clean up config files.
Privacy
This extension:
- Does NOT collect telemetry or send data to third parties
- Communicates only with Google APIs using your own credentials
- Stores credentials in VS Code's built-in SecretStorage (encrypted, per-user)
- OAuth refresh tokens never leave your machine
Links
By Renzo Johnson | Published by mercurial
