# @ergut/mcp-bigquery-server 中文文档

规范地址：https://npmcn.com/package/%40ergut/mcp-bigquery-server/

版本：1\.0\.4
npm 元数据更新时间：2026-04-20T15:22:10.996Z
中文译文更新时间：2026-11-13T20:51:18.526Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ergut/mcp-bigquery-server
原文对照：https://npmcn.com/package/%40ergut/mcp-bigquery-server/?lang=original
项目主页：https://oredata.com/
源码仓库：https://github.com/ergut/mcp-bigquery-server

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：70 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=14\.0\.0
- 运行依赖：2 个
- 首次发布：2024-12-03T20:33:10.164Z
- 最新版本发布：2026-04-20T15:22:10.896Z
- 近 30 天下载量：8335（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 1 个）

## 中文简介

用于与 BigQuery 数据库交互的 MCP 服务器

## 安装

```sh
npm install @ergut/mcp-bigquery-server
```

也可以使用：`pnpm add @ergut/mcp-bigquery-server`、`yarn add @ergut/mcp-bigquery-server`、`bun add @ergut/mcp-bigquery-server`

## README

# 大查询 MCP 服务器

[![smithery badge](https://smithery.ai/badge/@ergut/mcp-bigquery-server)](https://smithery.ai/protocol/@ergut/mcp-bigquery-server)

![BigQuery MCP Server Logo](https://npmcn.com/package/%40ergut/mcp-bigquery-server/assets/mcp-bigquery-server-logo.png)

## 这是什么

这是允许您 LLMs( 如 Claude) 直接与您的大查询数据交谈的服务器 ! 把它当成一个友好的翻译,坐在你的AI助手和数据库之间,确保他们能够安全而高效地聊天.

### 快速示例

```text
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%`),调整扫描频率,设定计费限额,并定义每表字段限制. 扫描器在下次运行时会拾取您的自定义模式,并自动保护所有数据集中的任何匹配列.

## 哪个设定适合你?

|  | 简单模式 | 保护模式 |
| --- | --- | --- |
| **使用时间** | 个人项目、非敏感数据 | PHI,PII,财务数据,HIPAA监管环境 |
| **安装** | `npx` 或Smithery——不需要本地设置 | 切开这个叉子,用一个 `config.json` |
| **实地限制** | 无 | 定义 `preventedFields` 以阻断敏感列 |
| **自动扫描器** | 不详 | 在所有数据集自动发现敏感列 |
| **设置** | [备选案文1](https://npmcn.com/package/%40ergut/mcp-bigquery-server/#readme-option-1-quick-install-via-smithery-recommended) 下级 | [备选案文2](https://npmcn.com/package/%40ergut/mcp-bigquery-server/#readme-option-2-manual-setup) 下级 |

**敏感数据的当地部署为何重要:** 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 服务器 [史密斯术](https://smithery.ai/protocol/@ergut/mcp-bigquery-server)在终端中运行此命令 :

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

安装器会提示您:

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

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

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

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

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

1.  **使用 Google 云认证** (选择一种方法):
    
    -   使用 Google Cloud CLI( 伟大的开发) :
        
        ```bash
        gcloud auth application-default login
        ```
        
    -   使用服务账户(建议生产):
        
        ```bash
        # 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.  **切开这个叉并在当地建造:**
    
    ```bash
    git clone https://github.com/drharunyuksel/mcp-bigquery-server
    cd mcp-bigquery-server
    npm install && npm run build
    ```
    
3.  **添加到您的 Claude 桌面配置** 将此添加到您的 `claude_desktop_config.json`数字 :
    
    -   配置文件的基本配置 :
        
        ```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"
              ]
            }
          }
        }
        ```
        
    -   有服务账户和配置文件 :
        
        ```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 结构

```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 类似自动发现模式 |
| `sensitiveFieldScanFrequencyDays` | `1` | 自动扫描之间的天数( A)`0` 要禁用) |

#### 命令行参数

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

使用服务账户的例子 :

```bash
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的本土结合 [列级安全](https://cloud.google.com/bigquery/docs/column-level-security-intro) 财务报告和审定财务报表 [授权意见](https://cloud.google.com/bigquery/docs/authorized-views)。 。 。 .

### 保护模式

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

| 模式 | 说明 | 默认时间 |
| --- | --- | --- |
| `off` | 无保护——所有桌子和字段都可以使用 | 没有配置文件 |
| `allowedTables` | 表格允许列表——仅可查询列表中的表格 | 必须明确设置 |
| `autoProtect` | 敏感字段的自动扫描,执行 `preventedFields` | 配置文件不存在 `protectionMode` 键 |

#### `allowedTables` 模式

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

```json
{
  "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 代理访问特定列 :

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

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

```sql
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代理从这个错误中学习,并自动调整它的查询. 它仍然可以运行不暴露个人敏感值的分析查询:

```sql
-- 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
```

**查询模式参考 :**

| 查询模式 | 行为 |
| --- | --- |
| `SELECT restricted_col FROM table` | 以错误消息被屏蔽 |
| `SELECT * FROM table` | 被封锁(将暴露受限制的字段) |
| `SELECT * EXCEPT(restricted_cols) FROM table` | 允许 |
| `COUNT(restricted_col)`, (中文(简体) ), `AVG(...)`, (中文(简体) ), `SUM(...)`, (中文(简体) ), `COUNTIF(...)` | 允许( 汇总不显示个人价值) |
| `MIN(restricted_col)`, (中文(简体) ), `MAX(restricted_col)` | 被屏蔽(返回实际个人价值) |
| `SELECT non_restricted_col FROM table` | 允许 |
| `SELECT id FROM table WHERE restricted_col = '...'` | 封锁(见下文注) |
| `SELECT id FROM table ORDER BY restricted_col` | 封锁(见下文注) |

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

**服务器侧日志 :** 每个被屏蔽的查询都登录在服务器侧面,让管理员了解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 手动扫描

随时进行扫描:

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

#### 您组织的自定义模式

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

```json
{
  "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`。随着您数据仓库的增长和新表格的添加,任何匹配您模式的列都是 **自动保护** 没有人工干预.

#### 扫描器配置

| 设置 | 默认 | 说明 |
| --- | --- | --- |
| `sensitiveFieldPatterns` | 包含姓名、联系人、身份、保险和秘密的内设套件 | SQL 喜欢匹配列名的图案 |
| `sensitiveFieldScanFrequencyDays` | `1` (日语) | 隔几天自动扫描 设定 `0` 以禁用自动扫描. |

### 需要权限

你需要一个这个:

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

## 本地构建( 可选) QQ

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

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

# Build
npm run build
```

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

-   **简单模式** (没有配置文件) :
    
    ```json
    {
      "mcpServers": {
        "bigquery": {
          "command": "node",
          "args": [
            "/path/to/your/clone/mcp-bigquery-server/dist/index.js",
            "--project-id",
            "your-project-id",
            "--location",
            "us-central1"
          ]
        }
      }
    }
    ```
    
-   **保护模式** (带有配置文件):
    
    ```json
    {
      "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.
```

## 常见问题

### @ergut/mcp-bigquery-server 是什么？

用于与 BigQuery 数据库交互的 MCP 服务器

### 如何安装 @ergut/mcp-bigquery-server？

在项目目录运行 npm install @ergut/mcp-bigquery-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp-server-bigquery，可以用 npx mcp-server-bigquery 直接运行。

### @ergut/mcp-bigquery-server 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/ergut\_\_mcp-bigquery-server 是否存在。

### @ergut/mcp-bigquery-server 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @ergut/mcp-bigquery-server 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=14\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ergut/mcp-bigquery-server 可以商用吗？

@ergut/mcp-bigquery-server 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ergut/mcp-bigquery-server 的下载量有多少？

根据 npm 官方下载统计，@ergut/mcp-bigquery-server 在 2026/10/14 – 2026/11/12 这 30 天内被下载 8,335 次，日均约 278 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ergut/mcp-bigquery-server 还在维护吗？

最新版本 1\.0\.4 发布于 2026/04/20（6 个月前）；至今共发布 5 个版本，其中过去 12 个月发布了 1 个；首次发布于 2024/12/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。