BigQuery MCP Server
Secure, read-only access to Google BigQuery datasets for LLMs, with field-level PII/PHI protection.
Add to your client
Copy the config for your MCP client and paste it into its config file.
npx -y @ergut/mcp-bigquery-server --project-id your-project-idPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"bigquery-mcp-server": {
"command": "npx",
"args": [
"-y",
"@ergut/mcp-bigquery-server",
"--project-id",
"your-project-id"
]
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Node.js 14 or higher
- Google Cloud project with BigQuery enabled
- Google Cloud CLI installed or a service account key file
- Any MCP-compatible client (Claude Desktop, Claude Code, etc.)
About BigQuery MCP Server
BigQuery MCP Server connects MCP-compatible clients (Claude Desktop, Claude Code, and other AI clients) to Google BigQuery, allowing users to ask questions about their data in plain English instead of writing SQL by hand. It is strictly read-only: a single query tool runs SELECT statements that are validated by BigQuery's dry-run planner before execution, and dataset table/view schemas are exposed as MCP resources for exploration. For regulated or sensitive environments, Protected Mode adds field-level restrictions (preventedFields), three protection modes (off, allowedTables, autoProtect), and an automated scanner that discovers sensitive columns across all datasets using configurable SQL LIKE patterns. Distributed as the npm package @ergut/mcp-bigquery-server and runnable via npx or a local build.
Tools & capabilities (1)
queryRun a read-only BigQuery SQL query. Accepts a `sql` string argument; only SELECT statements pass BigQuery's dry-run validation, and INFORMATION_SCHEMA queries are auto-qualified to the project. Results respect the configured maximumBytesBilled limit and any active field/table protection rules.
When to use it
- Ask natural-language questions about BigQuery data (e.g. 'What were our top 10 customers last month?') and get answers without writing SQL by hand
- Explore dataset schemas, including both tables and materialized views, with clear labeling of resource types
- Run ad-hoc analytical SELECT queries within a configurable per-query byte-billing limit
- Give AI agents read-only access to a data warehouse in HIPAA/PII/PHI-regulated environments while blocking sensitive columns via preventedFields
- Automatically discover and protect newly added sensitive columns across all datasets using the auto-scanner
Security notes
Read-only by design — only SELECT statements pass BigQuery's dry-run validation; mutating statements (INSERT, UPDATE, DELETE, DROP, TRUNCATE, EXPORT DATA, MERGE) are rejected. Protected Mode lets admins define preventedFields to block sensitive columns (PII/PHI/financial/secrets) from entering LLM responses, with an optional auto-scanner across all datasets. Per the README, field restrictions are cooperative guardrails for AI agents, not a hard SQL firewall against adversarial attackers (see PROTECTION.md). Query results are sent to the LLM provider for processing and thus leave your network; run locally for sensitive data. Configurable per-query billing cap (maximumBytesBilled, default 1GB) via config.json or --maximum-bytes-billed. Keep service account key files secure and never commit them.
BigQuery MCP Server FAQ
Can the AI agent modify or delete my data?
No. The server is read-only by design. Only SELECT statements are allowed and each query is validated by BigQuery's dry-run planner before execution, so INSERT, UPDATE, DELETE, DROP, TRUNCATE, EXPORT DATA, and MERGE are all rejected.
How does it authenticate to Google Cloud?
Either via Application Default Credentials (`gcloud auth application-default login`, good for development) or a service account key file passed with the --key-file argument (recommended for production). Keep service account key files secure and never commit them to version control.
What is the difference between Simple Mode and Protected Mode?
Simple Mode runs with no config file, applies safe defaults (1GB query limit) and no field restrictions — suitable for personal projects and non-sensitive data. Protected Mode is enabled by passing --config-file and lets you define preventedFields, choose a protectionMode (off, allowedTables, autoProtect), and run an auto-scanner that discovers sensitive columns across all datasets.
Do field restrictions fully prevent sensitive data exposure?
The README is explicit that field restrictions are cooperative guardrails for AI agents, not a hard SQL firewall against adversarial attackers. They ensure PHI/PII never enter the LLM conversation context for normal agent use; see PROTECTION.md for the full threat model. Because query results are sent to the LLM provider, running the server locally is recommended for sensitive data.
Which MCP clients are supported?
Any MCP-compatible client. The README shows config examples for Claude Desktop (claude_desktop_config.json) and Claude Code (.mcp.json); other clients use the same standard MCP server format — refer to your client's docs for the config file location.
Alternatives to BigQuery MCP Server
Compare all alternatives →
Google's official MCP server with prebuilt BigQuery tools, querying datasets via Application Default Credentials.
Read/write Postgres access plus index tuning, EXPLAIN plans, and database health analysis for AI agents.
Official Supabase server: manage tables, run SQL, branches, configs and edge functions from your AI client.
Compare BigQuery MCP Server with: