ergut/mcp-bigquery-server

What is this? 🤔
This is a server that lets your LLMs (like Claude) talk directly to your BigQuery data — **read-only, with no ability to mutate your warehouse**. Think of it as a friendly translator that sits between your AI assistant and your database, making sure they can chat securely and efficiently.
Quick Example
No more writing SQL queries by hand - just chat naturally with your data!
How Does It Work? 🛠️
This server uses the Model Context Protocol (MCP), which is like a universal translator for AI-database communication. MCP is supported by Claude Desktop, Claude Code, and a growing number of other AI clients.
Here's all you need to do:
1. Set up authentication (see below)
2. Add your project details to your MCP client's config file
3. Start chatting with your BigQuery data naturally!
What Can It Do? 📊
- **Read-only by design** — only SELECT statements are allowed. Every query is validated by BigQuery's own dry-run planner before execution, so INSERT, UPDATE, DELETE, DROP, TRUNCATE, EXPORT DATA, and MERGE are all rejected. The AI agent cannot mutate your warehouse, period.
- Run SQL queries by just asking questions in plain English
- Access both tables and materialized views in your datasets
- Explore dataset schemas with clear labeling of resource types (tables vs views)
- Analyze data within configurable safe limits (set via config.json or --maximum-bytes-billed)
- **Protect sensitive data** — define field-level access restrictions to prevent AI agents from reading PII, PHI, financial data, and secrets. The agent receives clear guidance on how to reformulate queries using aggregates or EXCEPT clauses, so it remains useful without exposing individual records.
- **Auto-discover sensitive fields** — automatically scan your entire BigQuery data warehouse for columns matching sensitive patterns (names, emails, SSNs, medical records, API keys, etc.) and add them to the restricted list. New tables and columns are protected automatically on each scan — no manual maintenance required.
- **Fully configurable** — everything is driven by config.json. Add your own detection patterns to match your organization's naming conventions (e.g., %guardian_name%, %beneficiary%), adjust scan frequency, set billing limits, and define per-table field restrictions. The scanner picks up your custom patterns on the next run and automatically protects any matching columns across all datasets.
Which Setup Is Right for You?
| | Simple Mode | Protected Mode |
|---|---|---|
| **Use when** | Personal projects, non-sensitive data | PHI, PII, financial data, HIPAA-regulated environments |
| **Install** | npx — no local setup needed | npx or local build with a config.json |
| **Field restrictions** | None | Define preventedFields to block sensitive columns |
| **Auto-scanner** | Not available | Discovers sensitive columns across all datasets automatically |
| **Setup** | Quick Setup below | Protected Mode Setup below |
**Why local deployment matters for sensitive data:** LLM inference happens in the cloud. When an AI agent queries BigQuery, the results are sent to the LLM provider's servers (Anthropic, OpenAI, etc.) for processing — they leave your network. BigQuery IAM controls who can *reach* your data; field restrictions control what the *AI agent surfaces into LLM responses*. These are different protection boundaries. Configuring preventedFields ensures PHI and PII never enter the LLM conversation context, regardless of how many queries the agent runs autonomously.
Quick Start 🚀
Prerequisites
- Node.js 14 or higher
- Google Cloud project with BigQuery enabled