AI导哈

BigQuery MCP服务器

一个允许LLM（如Claude）直接与BigQuery数据交互的服务器，提供安全高效的只读查询功能。

  • by ergut
  • TypeScript
  • 本地部署
  • 148 星标
  • 更新于
在 GitHub 查看 ergut/mcp-bigquery-server

使用说明

BigQuery MCP服务器

这是什么？ 🤔

这是一个让LLM（如Claude）直接与BigQuery数据通信的服务器-- 只读，无法更改仓库。把它想象成一个友好的翻译器，位于你的人工智能助手和数据库之间，确保他们可以安全有效地聊天。

快速示例

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

不再需要手工编写SQL查询，只需与您的数据自然聊天即可！

它是如何工作的？ 🛠️

该服务器使用模型上下文协议（MCP），它就像人工智能数据库通信的通用翻译器。MCP得到了Claude Desktop、Claude Code和越来越多的其他AI客户端的支持。

以下是您需要做的一切：

  1. 设置身份验证（见下文）
  2. 将项目详细信息添加到MCP客户端的配置文件中
  3. 开始自然地与您的BigQuery数据聊天！

它能做什么？ 📊

  • 按设计只读 --只有 SELECT 允许发表声明。每个查询在执行前都会经过BigQuery自己的模拟运行计划器的验证，因此 INSERT, UPDATE, DELETE, DROP, TRUNCATE, EXPORT DATA，以及 MERGE 都被拒绝了。人工智能代理不能改变你的仓库，仅此而已。
  • 只需用简单的英语提问即可运行SQL查询
  • 访问数据集中的表和物化视图
  • 探索数据集模式，明确标注资源类型（表与视图）
  • 在可配置的安全范围内分析数据（通过设置 config.json 或 --maximum-bytes-billed)
  • 保护敏感数据 --定义字段级访问限制，以防止AI代理读取PII、PHI、财务数据和机密。代理收到关于如何使用聚合或 EXCEPT 子句，因此它在不暴露单个记录的情况下仍然有用。
  • 自动发现敏感字段 -自动扫描整个BigQuery数据仓库中与敏感模式匹配的列（姓名、电子邮件、SSN、医疗记录、API密钥等），并将其添加到限制列表中。每次扫描时，新的表和列都会自动受到保护，无需手动维护。
  • 完全可配置 --一切都是由 config.json添加您自己的检测模式以匹配您组织的命名约定（例如。， %guardian_name%, %beneficiary%)，调整扫描频率，设置计费限制，并定义每个表的字段限制。扫描仪在下次运行时拾取您的自定义模式，并自动保护所有数据集中的任何匹配列。

哪种设置适合您？

简单模式 保护模式
使用时间 个人项目、非敏感数据 PHI、PII、财务数据、HIPAA监管环境
安装 npx --无需本地设置 npx 或本地构建 config.json
现场限制 无 定义 preventedFields 阻止敏感列
自动扫描仪 不可用 自动发现所有数据集中的敏感列
设置 快速设置 在......下面 保护模式设置 在......下面

为什么本地部署对敏感数据很重要： LLM推理发生在云中。当AI代理查询BigQuery时，结果会被发送到LLM提供商的服务器（Anthropic、OpenAI等）进行处理——它们会离开您的网络。BigQuery IAM控制谁可以 达到 您的数据；现场限制控制什么 AI代理表面生成LLM响应这些是不同的保护边界。配置 preventedFields 确保PHI和PII永远不会进入LLM对话上下文，无论代理自主运行多少查询。

快速开始🚀

先决条件

  • Node.js 14或更高版本
  • 启用BigQuery的Google Cloud项目
  • 已安装Google Cloud CLI或服务帐户密钥文件
  • 任何兼容MCP的客户端（克劳德桌面、克劳德代码等）

快速设置

  1. 使用Google Cloud进行身份验证：

    gcloud auth application-default login

  2. 添加到MCP客户端的配置中 （例如。， claude_desktop_config.json 对于克劳德桌面， .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
    • 使用服务帐户（建议用于生产）：
      # Save your service account key file and use --key-file parameter
# Remember to keep your service account key file secure and never commit it to version control

  2. 添加到MCP客户端的配置中 （例如。， claude_desktop_config.json 对于克劳德桌面， .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代理可以直接访问您的仓库时， 没有人在循环中阻止它读取敏感列A. SELECT * FROM patients 可能会暴露数千条PII/PHI记录，然后将结果发送给LLM提供商进行处理——它们会离开您的网络。

此服务器为管理员提供了对AI代理可以访问哪些列的精细控制。您定义 preventedFields 在 config.json 并且服务器阻止将这些列显示为LLM响应的查询。自动扫描仪发现敏感列 全部 您的数据集，因此随着仓库的增长，覆盖率保持最新。

诚实的警告： 字段限制是人工智能代理的合作护栏，而不是对抗敌对攻击者的硬SQL防火墙。看 保护.md 对于完整的威胁模型。

服务器支持三种保护模式，通过设置 protectionMode 在 config.json:

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

看 保护.md 有关完整配置、示例、查询模式参考、扫描程序设置和所需的IAM权限。

本地构建（可选）🔧

运行本地构建，而不是 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"
      ]
    }
  }
}

对于保护模式，添加 "--config-file", "/path/to/config.json" 到 args 数组（可选 "--key-file", "/path/to/service-account-key.json" 用于服务帐户身份验证）。

当前限制⚠️

  • JSON配置示例遵循标准MCP服务器格式。任何兼容MCP的客户端（Claude Desktop、Claude Code等）都可以使用它——有关配置文件的确切位置，请参阅客户端的文档
  • 每个查询的处理限制都是可配置的（在中设置 config.json 或通过 --maximum-bytes-billed)
  • 虽然支持表和视图，但一些复杂的视图类型可能存在局限性
  • config.json文件是可选的；如果没有，服务器将使用安全默认值

支持和资源💬

许可证📝

MIT许可证-请参阅 许可证 文件以获取详细信息。

作者✍️

萨利赫·埃尔古特

赞助

该项目由以下机构赞助：

版本历史📋

看 更改日志.md 用于更新和版本历史记录。

相关 MCP