大查询 MCP 服务器

这是什么

这是允许您 LLMs( 如 Claude) 直接与您的大查询数据交谈的服务器 ! 把它当成一个友好的翻译,坐在你的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-数据库通信的通用翻译. 虽然MCP被设计为与任何AI模型一起工作,但现在它可以作为克洛德桌面的开发者预览.

这就是你要做的:

1. 设置认证(见下文)
2. 将您的工程细节添加到 Claude 桌面配置文件
3. 开始自然地与你的大查询数据聊天!

我们能做什么

• 用简单的英语提问来运行 SQL 查询
• 访问数据集中的表格和已实现视图
• 探索具有明确资源类型标签的数据集计划(表与视图)
• 在可配置的安全限度内分析数据(通过配置.json配置)
• 保护敏感数据 ——定义现场访问限制,以阻止AI代理阅读PII,PHI,财务数据和秘密. 代理人在如何使用聚合物或 EXCEPT 因此,在不披露个别记录的情况下仍然有用.
• 自动发现敏感字段 ——自动扫描您整个大查询数据仓库,以查找匹配敏感图案的列(名称,电子邮件,SSN,医疗记录,API密钥等)并添加到限制列表中. 每次扫描时自动保护新的表格和列——不需要手动维护.
• 完全可配置 - 一切由我们驱动 config.json。添加你自己的检测模式,以匹配您的组织命名惯例(例如, %guardian_name%, (中文(简体) ), %beneficiary%),调整扫描频率,设定计费限额,并定义每表字段限制. 扫描器在下次运行时会拾取您的自定义模式,并自动保护所有数据集中的任何匹配列.

哪个设定适合你?

敏感数据的当地部署为何重要: LLM推断发生在云中. 当一个AI代理询问BigQuery时,结果被发送到LLM提供者的服务器(Anthropic,OpenAI等)进行处理——它们离开你的网络. 大查询 IAM 控制谁可以 到达 您的数据; 字段限制控制什么 AI 剂在 LLM 反应中浮出水面这些是不同的保护界限。 配置 preventedFields 确保 PHI 和 PII 永远不输入 LLM 对话框上下文,无论代理运行的查询次数如何.

快速启动 QQ

先决条件

• 节点.js 14或以上
• Google Cloud 工程已启用
• 已安装 Google Cloud CLI 或服务账户密钥文件
• Claude桌面( 目前唯一支持的 LLM 接口)

备选案文1:通过Smithery快速安装(建议——简单模式)

为 Claude 桌面自动安装大查询 MCP 服务器 史密斯术在终端中运行此命令 :

npx @smithery/cli install @ergut/mcp-bigquery-server --client claude

安装器会提示您:

• 您的谷歌云项目 ID
• 大查询位置( 默认为 us- Central1)

一旦配置完毕, Smithery 将自动更新您的 Claude 桌面配置并重新启动应用程序 .

备选案文2:手动设置(保护模式——用于敏感数据)

如果您处理敏感数据或需要外地访问限制:

说明: 这个 npx @ergut/mcp-bigquery-server 命令安装已发布的上游软件包,该软件包尚未包括“保护模式”。 直至 此公关 合并并发布新版本,使用下面的本地建筑.

1. 使用 Google 云认证 (选择一种方法):

   • 使用 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. 切开这个叉并在当地建造:

   git clone https://github.com/drharunyuksel/mcp-bigquery-server
   cd mcp-bigquery-server
   npm install && npm run build
   

3. 添加到您的 Claude 桌面配置 将此添加到您的 claude_desktop_config.json数字 :

   • 配置文件的基本配置 :

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

   • 有服务账户和配置文件 :

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

4. 开始聊天! 打开 Claude 桌面, 开始询问您的数据 .

配置

服务器支持可选 config.json 用于高级配置的文件。 没有配置文件(即没有) --config-file 旗下),服务器运行在有安全默认的简单模式下(1GB查询限制,没有字段限制). 为了保护,通过 --config-file /path/to/config.json 当启动服务器时.

配置. 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
}

命令行参数

• --project-id: (需要) 您的 Google Cloud 项目 ID
• --location: (可选)大查询位置,默认为"US"
• --key-file: (可选) 服务账户密钥 JSON 文件路径
• --config-file: (可选) 配置文件路径, 默认为“ config.json”
• --maximum-bytes-billed: (可选) 覆盖为查询计费的最大字节, 覆盖配置. 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

保护敏感数据QQ

数据仓库经常包含高度敏感的信息——病人记录,社会保障号码,财务数据,个人联系细节,认证机密等. 当一个AI代理可以直接访问 查询您的大查询仓库, 循环中没有人能阻止它读取敏感的列。简单的查询类似 SELECT * FROM patients 可能会在一次答复中披露数千PII/PHI记录.

这个服务器让管理员对AI代理可以访问的列进行精细控制,确保敏感数据保留被保护,同时仍然允许AI对非敏感字段进行有用的分析查询.

安全模型:合作护栏,不是SQL防火墙

重要内容: 此服务器中的字段限制和表格允许列表被设计为 人工智能特工的合作护卫而不是作为对抗攻击者的安全界限.

威胁模式是直截了当的:当一个AI代理询问您大查询仓库时,查询结果会被发送到LLM提供者的服务器. 现场限制使得毒剂无意中在这些结果中包括了敏感的一栏(PII,PHI,秘密). 当代理遇到限制错误时,它会读取错误消息中的指针并重写它的查询——使用集合函数, EXCEPT 条款,或只是删除所限制的字段。 在实践中,大赦国际人员立即和一贯地合作.

该系统使用基于regex的SQL分析来检测受限制的战地使用. 我们在开发过程中进行了穿透测试,并固定了几个绕行向量(结构化外形扩展、共通逃逸、隐含) SELECT *) (中文(简体) ). 然而,基于regex的解析不能保证覆盖每一个可能的 SQL 构造——可能存在涉及深层嵌入式CTE的边缘案例,异地大查询语法,或对抗式的查询设计. 执行逻辑旨在 关闭失败 (阻断模糊的查询而不是允许查询),但这不等同于数据库一级的安全政策.

这是:

• 防止AI代理在正常使用时访问敏感数据的有效指导
• 安全网,可捕捉常见的查询模式SELECT *,直接字段引用,别名)
• 对通过穿透测试发现的已知绕行技术进行加固

这不是:

• 替换大查询 IAM、列级安全或行级访问政策
• 对恶意的人类故意编造绕行查询的辩护
• 认证的 SQL 解析器 — 它使用图案匹配, 不是完整的 AST

对于需要严格合规保障的环境,将这些护栏和大Query的本土结合 列级安全 财务报告和审定财务报表 授权意见。 。 。 .

保护模式

服务器支持三种保护模式,通过 protectionMode 内 config.json数字 :

allowedTables 模式

将AI代理限制在一组特定的表格内。 对任何其他表格的查询立即被拒绝。 在允许的表格中选择定义字段限制 :

{
  "protectionMode": "allowedTables",
  "maximumBytesBilled": "10000000000",
  "allowedTables": [
    "analytics.page_views",
    "analytics.sessions",
    "reporting.daily_summary"
  ],
  "preventedFieldsInAllowedTables": {
    "analytics.page_views": ["user_ip", "user_agent"]
  }
}

• preventedFieldsInAllowedTables 是可选的——默认为 {} (允许的表格中没有字段限制)
• 自动扫描的 没有 在此模式下运行——所有限制都是手动配置的
• INFORMATION_SCHEMA 总是允许查询 用于计划发现

autoProtect 模式(外地限制)

原保护模式. 为敏感列自动扫描您的大查询数据集并强制执行 preventedFields手动输入 preventedFields 持续通过扫描(合并仅是添加剂)。 详见下文.

没有配置文件 protectionMode 继续工作——它们默认为 autoProtect 用于向后兼容.

外地访问限制

定义 preventedFields 在您的配置中阻止 AI 代理访问特定列 :

{
  "preventedFields": {
    "healthcare.patients": ["first_name", "last_name", "ssn", "date_of_birth", "email"],
    "billing.transactions": ["credit_card_number", "bank_account"]
  }
}

当AI代理试图访问一个被限制的字段时会发生什么:

SELECT first_name, last_name, diagnosis FROM healthcare.patients

服务器屏蔽了查询并返回一个清晰,启发性错误 :

Restricted fields detected for table "healthcare.patients" columns "first_name", "last_name".
You can only use these columns inside ["count", "countif", "avg", "sum"]
aggregate functions or exclude them with SELECT * EXCEPT (...).

AI代理从这个错误中学习,并自动调整它的查询. 它仍然可以运行不暴露个人敏感值的分析查询:

-- Allowed: aggregate functions don't expose individual values
SELECT COUNT(first_name) AS patient_count, diagnosis
FROM healthcare.patients
GROUP BY diagnosis

-- Allowed: explicitly excluding restricted fields
SELECT * EXCEPT(first_name, last_name, ssn, date_of_birth, email)
FROM healthcare.patients

查询模式参考 :

注: 限制字段、命令BY和其他条款被封锁不只是SELECT里的田园 尽管查询结果并不包含被限制的一栏,但完整的SQL查询文本作为对话的一部分被发送给了LLM提供者. 查询像 WHERE email = '[email protected]' 表示受限值出现在发送到云的提示中. 执行检查整个查询,以防止受限制的数据以任何形式离开您的网络.

服务器侧日志 : 每个被屏蔽的查询都登录在服务器侧面,让管理员了解AI代理试图访问的内容:

Query tool error: Error: Restricted fields detected for table "healthcare.patients" columns "first_name", "last_name".

自动敏感场扫描仪

手动列出数百个表格中每一个敏感一栏是不切实际的。 服务器包括一个自动扫描仪,可以发现跨越的敏感列 全部 通过查询查询查询您最大的数据集 INFORMATION_SCHEMA.COLUMNS 与可配置的 SQL 像图案。 发现的字段自动添加到 preventedFields 在你的配置.

如何运作

1. 扫描器运行 SQL 类似模式, 匹配您大查询项目中的所有列名
2. 匹配图案的列 %first_name%, (中文(简体) ), %ssn%, (中文(简体) ), %email% 确定为敏感
3. 发现的列被合并到您的配置中 preventedFields
4. 合并是 仅添加剂 ——人工添加的限制永远不会被去除

服务器启动时自动扫描

MCP 服务器启动时, 它会检查配置文件是否基于 Stale sensitiveFieldScanFrequencyDays。如果 stale,它会自动扫描和更新配置 :

Config is stale (scan frequency: 1 day(s)), running sensitive field scan...
Scanning all datasets for sensitive fields...
Found 1166 sensitive column(s) across 278 table(s)
Scan complete: config updated with 278 tables.

这意味着 自动保护带有敏感列的新表格 没有手动配置。 随着数据仓库的扩大 扫描仪不断更新.

通过 CLI 手动扫描

随时进行扫描:

npm run scan-fields -- --project-id your-project-id --config-file ./config.json

您组织的自定义模式

默认模式涵盖常见的命名惯例(名称,电子邮件,SSN,出生日期,医疗记录号码,保险ID,密码,API密钥等),但每个组织都有自己的. 添加自定义模式以匹配您的方案 :

{
  "sensitiveFieldPatterns": [
    "%first_name%", "%last_name%", "%email%", "%ssn%",
    "%date_of_birth%", "%password%", "%api_key%",
    "%guardian_name%",
    "%emergency_contact%",
    "%beneficiary%",
    "%next_of_kin%"
  ]
}

在下一个自动扫描( 或手动) 上 npm run scan-fields),扫描仪将匹配您新模式的列取出并自动添加到 preventedFields。随着您数据仓库的增长和新表格的添加,任何匹配您模式的列都是 自动保护 没有人工干预.

扫描器配置

需要权限

你需要一个这个:

• roles/bigquery.user (建议)
• 或两者兼有:
  • roles/bigquery.dataViewer
  • roles/bigquery.jobUser

本地构建( 可选) QQ

运行一个本地建筑而不是 npx 用于促进、测试更改或运行被绑定的版本。 支持简单模式和保护模式.

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

# Build
npm run build

然后更新您的 Claude 桌面配置以指向您的本地建筑 :

• 简单模式 (没有配置文件) :

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

• 保护模式 (带有配置文件):

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

## Current Limitations ⚠️

- The configuration examples above are shown for Claude Desktop and Claude Code, but any MCP-compatible client can use this server — provide the same JSON configuration to your AI agent and it will adapt to its own setup
- Queries are read-only with configurable processing limits (set in config.json)
- While both tables and views are supported, some complex view types might have limitations
- A config.json file is optional; without one the server uses safe defaults

## Support & Resources 💬

- 🐛 [Report issues](https://github.com/ergut/mcp-bigquery-server/issues)
- 💡 [Feature requests](https://github.com/ergut/mcp-bigquery-server/issues)
- 📖 [Documentation](https://github.com/ergut/mcp-bigquery-server)

## License 📝

MIT License - See [LICENSE](LICENSE) file for details.

## Author ✍️ 

Salih Ergüt

## Sponsorship

This project is proudly sponsored by:

<div align="center">
  <a href="https://www.oredata.com">
    <img src="assets/oredata-logo-nobg.png" alt="OREDATA" width="300"/>
  </a>
</div>

## Version History 📋

See [CHANGELOG.md](CHANGELOG.md) for updates and version history.