Skip to content
Back to search

mcp-bigquery-server

A Model Context Protocol (MCP) server that provides secure, read-only access to BigQuery datasets. Enables Large Language Models (LLMs) to safely query and analyze data through a standardized interface.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ergut--mcp-bigquery-server/badge.svg)](/listings/ergut--mcp-bigquery-server)

HTML

<a href="/listings/ergut--mcp-bigquery-server"><img src="/api/listings/ergut--mcp-bigquery-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

| | 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](#quick-setup) below | [Protected Mode Setup](#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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 276 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # BigQuery MCP Server
  2. <div align="center">
  3. <img src="assets/mcp-bigquery-server-logo.png" alt="BigQuery MCP Server Logo" width="400"/>
  4. </div>
  5. ## What is this? 🤔
  6. 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.
  7. ### Quick Example
  8. ```text
  9. You: "What were our top 10 customers last month?"
  10. Claude: *queries your BigQuery database and gives you the answer in plain English*
  11. ```
  12. No more writing SQL queries by hand - just chat naturally with your data!
  13. ## How Does It Work? 🛠️
  14. 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.
  15. Here's all you need to do:
  16. 1. Set up authentication (see below)
  17. 2. Add your project details to your MCP client's config file
  18. 3. Start chatting with your BigQuery data naturally!
  19. ### What Can It Do? 📊
  20. - **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.
  21. - Run SQL queries by just asking questions in plain English
  22. - Access both tables and materialized views in your datasets
  23. - Explore dataset schemas with clear labeling of resource types (tables vs views)
  24. - Analyze data within configurable safe limits (set via `config.json` or `--maximum-bytes-billed`)
  25. - **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.
  26. - **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.
  27. - **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.
  28. ## Which Setup Is Right for You?
  29. | | Simple Mode | Protected Mode |
  30. |---|---|---|
  31. | **Use when** | Personal projects, non-sensitive data | PHI, PII, financial data, HIPAA-regulated environments |
  32. | **Install** | `npx` — no local setup needed | `npx` or local build with a `config.json` |
  33. | **Field restrictions** | None | Define `preventedFields` to block sensitive columns |
  34. | **Auto-scanner** | Not available | Discovers sensitive columns across all datasets automatically |
  35. | **Setup** | [Quick Setup](#quick-setup) below | [Protected Mode Setup](#protected-mode-setup) below |
  36. **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.
  37. ## Quick Start 🚀
  38. ### Prerequisites
  39. - Node.js 14 or higher
  40. - Google Cloud project with BigQuery enabled
  41. - Either Google Cloud CLI installed or a service account key file
  42. - Any MCP-compatible client (Claude Desktop, Claude Code, etc.)
  43. ### Quick Setup
  44. 1. **Authenticate with Google Cloud:**
  45. ```bash
  46. gcloud auth application-default login
  47. ```
  48. 2. **Add to your MCP client's config** (e.g., `claude_desktop_config.json` for Claude Desktop, `.mcp.json` for Claude Code):
  49. ```json
  50. {
  51. "mcpServers": {
  52. "bigquery": {
  53. "command": "npx",
  54. "args": [
  55. "-y",
  56. "@ergut/mcp-bigquery-server",
  57. "--project-id",
  58. "your-project-id"
  59. ]
  60. }
  61. }
  62. }
  63. ```
  64. 3. **Start chatting!** Open your MCP client and ask questions about your data.
  65. ### Protected Mode Setup
  66. For sensitive data with field-level restrictions:
  67. 1. **Authenticate with Google Cloud** (choose one method):
  68. - Using Google Cloud CLI (great for development):
  69. ```bash
  70. gcloud auth application-default login
  71. ```
  72. - Using a service account (recommended for production):
  73. ```bash
  74. # Save your service account key file and use --key-file parameter
  75. # Remember to keep your service account key file secure and never commit it to version control
  76. ```
  77. 2. **Add to your MCP client's config** (e.g., `claude_desktop_config.json` for Claude Desktop, `.mcp.json` for Claude Code):
  78. - With Application Default Credentials:
  79. ```json
  80. {
  81. "mcpServers": {
  82. "bigquery": {
  83. "command": "npx",
  84. "args": [
  85. "-y",
  86. "@ergut/mcp-bigquery-server",
  87. "--project-id",
  88. "your-project-id",
  89. "--location",
  90. "us-central1",
  91. "--config-file",
  92. "/path/to/config.json"
  93. ]
  94. }
  95. }
  96. }
  97. ```
  98. - With a service account key file:
  99. ```json
  100. {
  101. "mcpServers": {
  102. "bigquery": {
  103. "command": "npx",
  104. "args": [
  105. "-y",
  106. "@ergut/mcp-bigquery-server",
  107. "--project-id",
  108. "your-project-id",
  109. "--location",
  110. "us-central1",
  111. "--key-file",
  112. "/path/to/service-account-key.json",
  113. "--config-file",
  114. "/path/to/config.json"
  115. ]
  116. }
  117. }
  118. }
  119. ```
  120. 3. **Start chatting!**
  121. Open your MCP client and start asking questions about your data.
  122. ## Configuration
  123. The server supports an optional `config.json` file for advanced configuration. Without a config file (i.e., no `--config-file` flag), the server runs in Simple Mode with safe defaults (1GB query limit, no field restrictions). To enable protection, pass `--config-file /path/to/config.json` when starting the server.
  124. ### config.json Structure
  125. ```json
  126. {
  127. "maximumBytesBilled": "1000000000",
  128. "preventedFields": {
  129. "healthcare.patients": ["first_name", "last_name", "ssn", "date_of_birth", "email"],
  130. "billing.transactions": ["credit_card_number", "bank_account"]
  131. },
  132. "sensitiveFieldPatterns": [
  133. "%first_name%", "%last_name%", "%email%",
  134. "%ssn%", "%date_of_birth%", "%password%"
  135. ],
  136. "sensitiveFieldScanFrequencyDays": 1
  137. }
  138. ```
  139. | Setting | Default | Description |
  140. |---------|---------|-------------|
  141. | `maximumBytesBilled` | `"1000000000"` (1GB) | Maximum bytes billed per query |
  142. | `preventedFields` | `{}` | Table-to-columns mapping of restricted fields |
  143. | `sensitiveFieldPatterns` | Built-in set | SQL LIKE patterns for auto-discovery |
  144. | `sensitiveFieldScanFrequencyDays` | `1` | Days between auto-scans (`0` to disable) |
  145. ### Command Line Arguments
  146. - `--project-id`: (Required) Your Google Cloud project ID
  147. - `--location`: (Optional) BigQuery location, defaults to 'US'
  148. - `--key-file`: (Optional) Path to service account key JSON file
  149. - `--config-file`: (Optional) Path to a configuration file. If omitted, the server runs in Simple Mode with no protection — there is no implicit default of `./config.json`
  150. - `--maximum-bytes-billed`: (Optional) Override maximum bytes billed for queries, overrides config.json value
  151. Example using service account:
  152. ```bash
  153. npx @ergut/mcp-bigquery-server --project-id your-project-id --location europe-west1 --key-file /path/to/key.json --config-file /path/to/config.json --maximum-bytes-billed 2000000000
  154. ```
  155. ## Protecting Sensitive Data 🔒
  156. Data warehouses often contain highly sensitive information — patient records, social security numbers, financial data, personal contact details, and authentication secrets. When an AI agent has direct access to query your warehouse, **there is no human in the loop to prevent it from reading sensitive columns**. A `SELECT * FROM patients` could expose thousands of PII/PHI records, and the results are then sent to the LLM provider for processing — they leave your network.
  157. This server gives administrators fine-grained control over which columns an AI agent can access. You define `preventedFields` in `config.json` and the server blocks queries that would surface those columns into LLM responses. An automated scanner discovers sensitive columns across **all** your datasets, so coverage stays current as your warehouse grows.
  158. > **Honest caveat:** Field restrictions are cooperative guardrails for AI agents — not a hard SQL firewall against adversarial attackers. See [PROTECTION.md](PROTECTION.md#security-model-cooperative-guardrails-not-a-sql-firewall) for the full threat model.
  159. The server supports three protection modes, set via `protectionMode` in `config.json`:
  160. | Mode | Description |
  161. |---|---|
  162. | `off` | No protection — all tables and fields accessible (default when no config file is provided) |
  163. | `allowedTables` | Table allowlist — only listed tables can be queried, with optional field restrictions within them |
  164. | `autoProtect` | Auto-scans your datasets for sensitive columns and enforces `preventedFields` |
  165. **See [PROTECTION.md](PROTECTION.md)** for full configuration, examples, the query pattern reference, scanner setup, and required IAM permissions.
  166. ## Local Build (Optional) 🔧
  167. Run a local build instead of `npx` — useful for contributing, testing changes, or running a pinned version. Supports both Simple and Protected Mode.
  168. ```bash
  169. # Clone and install
  170. git clone https://github.com/ergut/mcp-bigquery-server
  171. cd mcp-bigquery-server
  172. npm install
  173. # Build
  174. npm run build
  175. ```
  176. Then point your MCP client config to the local build:
  177. ```json
  178. {
  179. "mcpServers": {
  180. "bigquery": {
  181. "command": "node",
  182. "args": [
  183. "/path/to/your/clone/mcp-bigquery-server/dist/index.js",
  184. "--project-id",
  185. "your-project-id",
  186. "--location",
  187. "us-central1"
  188. ]
  189. }
  190. }
  191. }
  192. ```
  193. For Protected Mode, add `"--config-file", "/path/to/config.json"` to the `args` array (and optionally `"--key-file", "/path/to/service-account-key.json"` for service account auth).
  194. ## Current Limitations ⚠️
  195. - The JSON configuration examples follow the standard MCP server format. Any MCP-compatible client (Claude Desktop, Claude Code, etc.) can use it — refer to your client's documentation for the exact config file location
  196. - Processing limits are configurable per query (set in `config.json` or via `--maximum-bytes-billed`)
  197. - While both tables and views are supported, some complex view types might have limitations
  198. - A config.json file is optional; without one the server uses safe defaults
  199. ## Support & Resources 💬
  200. - 🐛 [Report issues](https://github.com/ergut/mcp-bigquery-server/issues)
  201. - 💡 [Feature requests](https://github.com/ergut/mcp-bigquery-server/issues)
  202. - 📖 [Documentation](https://github.com/ergut/mcp-bigquery-server)
  203. ## License 📝
  204. MIT License - See [LICENSE](LICENSE) file for details.
  205. ## Author ✍️
  206. Salih Ergüt
  207. ## Sponsorship
  208. This project is proudly sponsored by:
  209. <div align="center">
  210. <a href="https://www.oredata.com">
  211. <img src="assets/oredata-logo-nobg.png" alt="OREDATA" width="300"/>
  212. </a>
  213. </div>
  214. ## Version History 📋
  215. See [CHANGELOG.md](CHANGELOG.md) for updates and version history.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.