BigQuery MCP Server

BigQuery MCP 服务

这是什么？🤔

这是一个服务，可让你的大模型（例如 Claude）直接访问 BigQuery 数据——只读，无法修改数据仓库。可以把它看作一个友好的翻译器，位于 AI 助手和数据库之间，确保两者能够安全、高效地交流。

快速示例

You: "What were our top 10 customers last month?"
Claude: *queries your BigQuery database and gives you the answer in plain English*

无需再手动编写 SQL 查询，只需用自然语言与你的数据交流！

它如何工作？🛠️

此服务使用模型上下文协议（MCP），它就像 AI 与数据库通信的通用翻译器。Claude Desktop、Claude Code 以及越来越多的其他 AI 客户端均支持 MCP。

你只需完成以下操作：

1. 设置身份验证（见下文）
2. 将项目详情添加到 MCP 客户端的配置文件中
3. 开始用自然语言与你的 BigQuery 数据交流！

它能做什么？📊

• 默认只读——仅允许使用 SELECT 语句。执行前，每个查询都会由 BigQuery 自带的试运行规划器进行验证，因此 INSERT、UPDATE、DELETE、DROP、TRUNCATE、EXPORT DATA 和 MERGE 都会被拒绝。AI Agent 绝不能修改你的数据仓库。
• 只需用通俗英语提问，即可运行 SQL 查询
• 访问数据集中的表和物化视图
• 清晰标注资源类型（表与视图），探索数据集架构
• 在可配置的安全限制内分析数据（通过 config.json 或 --maximum-bytes-billed 设置）
• 保护敏感数据——定义字段级访问限制，防止 AI Agent 读取 PII、PHI、财务数据和机密信息。Agent 会收到明确指引，了解如何使用聚合函数或 EXCEPT 子句改写查询，从而在不暴露个人记录的情况下继续提供帮助。
• 自动发现敏感字段——自动扫描整个 BigQuery 数据仓库，查找与敏感模式匹配的列（姓名、电子邮件、SSN、医疗记录、API 密钥等），并将其加入受限列表。每次扫描都会自动保护新表和新列，无需手动维护。
• 完全可配置——所有设置均由 config.json 控制。添加自定义检测模式以匹配组织的命名惯例（例如 %guardian_name%、%beneficiary%），调整扫描频率、设置账单限制，并定义每张表的字段限制。扫描器会在下次运行时应用你的自定义模式，并自动保护所有数据集中的匹配列。

哪种设置适合你？

	简易模式	受保护模式
适用场景	个人项目、非敏感数据	PHI、PII、财务数据、受 HIPAA 监管的环境
安装方式	npx——无需本地设置	npx 或使用 config.json 进行本地构建
字段限制	无	定义 preventedFields 以阻止访问敏感列
自动扫描器	不提供	自动发现所有数据集中的敏感列
设置指南	下方的快速设置	下方的受保护模式设置

**敏感数据为何需要本地部署：**大模型推理在云端进行。当 AI Agent 查询 BigQuery 时，查询结果会发送到大模型提供商（Anthropic、OpenAI 等）的服务器进行处理——也就是说，数据会离开你的网络。BigQuery IAM 控制谁可以访问你的数据；字段限制则控制AI Agent 会将哪些内容呈现在大模型回复中。这是两道不同的保护边界。配置 preventedFields 可确保 PHI 和 PII 永远不会进入大模型对话上下文，无论 Agent 自主运行多少次查询。

快速开始 🚀

前置条件

• Node.js 14 或更高版本
• 已启用 BigQuery 的 Google Cloud 项目
• 已安装 Google Cloud CLI，或拥有服务账号密钥文件
• 任意兼容 MCP 的客户端（Claude Desktop、Claude Code 等）

快速设置

1. 通过 Google Cloud 进行身份验证：

   gcloud auth application-default login
   

2. 添加到 MCP 客户端的配置中（例如，Claude Desktop 使用 claude_desktop_config.json，Claude Code 使用 .mcp.json）：

   {
     "mcpServers": {
       "bigquery": {
         "command": "npx",
         "args": [
           "-y",
           "@ergut/mcp-bigquery-server",
           "--project-id",
           "your-project-id"
         ]
       }
     }
   }
   

3. 开始聊天！ 打开 MCP 客户端，就数据提出问题。

受保护模式设置

对于具有字段级限制的敏感数据：

1. 通过 Google Cloud 进行身份验证（选择一种方法）：

   • 使用 Google Cloud CLI（非常适合开发）：

     gcloud auth application-default login
     

   • 使用服务账号（推荐用于生产环境）：

     # 保存服务账号密钥文件，并使用 --key-file 参数
     # 请务必妥善保管服务账号密钥文件，切勿将其提交到版本控制系统
     

2. 添加到 MCP 客户端的配置中（例如，Claude Desktop 使用 claude_desktop_config.json，Claude Code 使用 .mcp.json）：

   • 使用应用默认凭证：

     {
       "mcpServers": {
         "bigquery": {
           "command": "npx",
           "args": [
             "-y",
             "@ergut/mcp-bigquery-server",
             "--project-id",
             "your-project-id",
             "--location",
             "us-central1",
             "--config-file",
             "/path/to/config.json"
           ]
         }
       }
     }
     

   • 使用服务账号密钥文件：

     {
       "mcpServers": {
         "bigquery": {
           "command": "npx",
           "args": [
             "-y",
             "@ergut/mcp-bigquery-server",
             "--project-id",
             "your-project-id",
             "--location",
             "us-central1",
             "--key-file",
             "/path/to/service-account-key.json",
             "--config-file",
             "/path/to/config.json"
           ]
         }
       }
     }
     

3. 开始聊天！ 打开 MCP 客户端，开始就数据提问。

配置

服务支持可选的 config.json 文件，用于高级配置。如果没有配置文件（即未设置 --config-file 标志），服务将以简单模式运行，并采用安全默认值（查询上限为 1GB，不限制字段）。要启用保护，请在启动服务时传入 --config-file /path/to/config.json。

config.json 结构

{
  "maximumBytesBilled": "1000000000",
  "preventedFields": {
    "healthcare.patients": ["first_name", "last_name", "ssn", "date_of_birth", "email"],
    "billing.transactions": ["credit_card_number", "bank_account"]
  },
  "sensitiveFieldPatterns": [
    "%first_name%", "%last_name%", "%email%",
    "%ssn%", "%date_of_birth%", "%password%"
  ],
  "sensitiveFieldScanFrequencyDays": 1
}

设置	默认值	描述
maximumBytesBilled	"1000000000"（1GB）	每次查询的最高计费字节数
preventedFields	{}	受限字段的表到列映射
sensitiveFieldPatterns	内置集合	用于自动发现的 SQL LIKE 模式
sensitiveFieldScanFrequencyDays	1	自动扫描间隔天数（设为 0 可禁用）

命令行参数

• --project-id：（必需）Google Cloud 项目 ID
• --location：（可选）BigQuery 位置，默认为 'US'
• --key-file：（可选）服务账号密钥 JSON 文件的路径
• --config-file：（可选）配置文件的路径。省略时，服务将以无保护的简单模式运行——不会默认使用 ./config.json
• --maximum-bytes-billed：（可选）覆盖查询的最高计费字节数，优先于 config.json 中的值

使用服务账号的示例：

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

保护敏感数据 🔒

数据仓库通常包含高度敏感的信息——患者记录、社会安全号码、财务数据、个人联系方式和身份验证密钥。当 AI Agent 可以直接查询你的数据仓库时，没有人工介入来阻止它读取敏感列。一条 SELECT * FROM patients 就可能暴露数千条 PII/PHI 记录，而查询结果随后会发送给大模型提供商进行处理——它们会离开你的网络。

此服务让管理员能够精细控制 AI Agent 可以访问哪些列。你可以在 config.json 中定义 preventedFields，服务会阻止可能将这些列暴露在大模型回复中的查询。自动扫描器会发现所有数据集中的敏感列，因此随着数据仓库扩展，保护范围也能保持最新。

**坦诚说明：**字段限制是为 AI Agent 提供的协作式防护措施——并非用于抵御恶意攻击者的强制性 SQL 防火墙。完整的威胁模型请参阅 PROTECTION.md。

此服务支持三种保护模式，通过 config.json 中的 protectionMode 设置：

模式	描述
off	不启用保护——可访问所有表和字段（未提供配置文件时的默认模式）
allowedTables	表允许列表——只能查询列出的表，并可选择限制这些表中的字段
autoProtect	自动扫描数据集中的敏感列并强制执行 preventedFields

完整配置、示例、查询模式参考、扫描器设置和所需的 IAM 权限，请参阅 PROTECTION.md。

本地构建（可选） 🔧

运行本地构建，而非使用 npx——适用于参与贡献、测试更改或运行固定版本。支持简单模式和保护模式。

# Clone and install
git clone https://github.com/ergut/mcp-bigquery-server
cd mcp-bigquery-server
npm install

# Build
npm run build

然后将 MCP 客户端配置指向本地构建：

{
  "mcpServers": {
    "bigquery": {
      "command": "node",
      "args": [
        "/path/to/your/clone/mcp-bigquery-server/dist/index.js",
        "--project-id",
        "your-project-id",
        "--location",
        "us-central1"
      ]
    }
  }
}

如需使用保护模式，请在 args 数组中添加 "--config-file", "/path/to/config.json"（使用服务账号进行身份验证时，还可选择添加 "--key-file", "/path/to/service-account-key.json"）。

当前限制 ⚠️

• JSON 配置示例遵循标准的 MCP 服务格式。任何兼容 MCP 的客户端（Claude Desktop、Claude Code 等）都可以使用——具体的配置文件位置请参阅客户端文档
• 每次查询的处理限制均可配置（在 config.json 中设置，或通过 --maximum-bytes-billed 设置）
• 虽然支持表和视图，但某些复杂的视图类型可能存在限制
• config.json 文件为可选；未提供时，服务会使用安全默认值

支持与资源 💬

• 🐛 报告问题
• 💡 功能请求
• 📖 文档

许可证 📝

MIT 许可证——详情请参阅 LICENSE 文件。

作者 ✍️

Salih Ergüt

赞助

本项目由以下机构鼎力赞助：

版本历史 📋

更新内容和版本历史请参阅 CHANGELOG.md。