/ 目录 / 演练场 / mcp-bigquery-server
● 社区 ergut ⚡ 即开即用

mcp-bigquery-server

作者 ergut · ergut/mcp-bigquery-server

从 Claude 对 BigQuery 的只读自然语言查询 —— 支持 schema 探索、查询限制、PII 字段限制 —— 使用服务账号认证。

mcp-bigquery-server 是一个 Node MCP,为 LLM 提供安全的只读访问 BigQuery 数据集。支持可配置的扫描字节数查询限制(默认 1GB),支持字段级的 PII/PHI 限制,可通过 Smithery 安装或使用服务账号凭据手动配置。

为什么要用

核心特性

实时演示

实际使用效果

bigquery-server.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "bigquery-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-bigquery-server"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "bigquery-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-bigquery-server"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "bigquery-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-bigquery-server"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "bigquery-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-bigquery-server"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "bigquery-server",
      "command": "npx",
      "args": [
        "-y",
        "mcp-bigquery-server"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "bigquery-server": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcp-bigquery-server"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add bigquery-server -- npx -y mcp-bigquery-server

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: mcp-bigquery-server

无需编写 SQL,直接从 BigQuery 回答产品/增长问题

👤 拥有 BQ 数据仓库的 PM、增长分析师 ⏱ ~15 min intermediate

何时使用: 你需要回答的问题的答案在 BQ 的事件表中。

前置条件
  • 具有 BQ Data Viewer + Job User 权限的 GCP 服务账号 — IAM > 创建服务账号;下载 JSON 密钥
步骤
  1. 发现表
    列出 analytics 数据集中的所有表。描述 eventsusers✓ 已复制
    → Schema 信息
  2. 提出问题
    有多少用户在 2026 年 3 月注册后的 7 天内触发了 'aha_moment' 事件?✓ 已复制
    → 数值答案和 SQL 查询
  3. 注意事项
    有什么需要注意的吗?时区、删除、测试用户?✓ 已复制
    → 真实的注意事项

结果: 几分钟内得到答案,不用再去找数据团队提工单。

注意事项
  • 在大型事实表上运行 SELECT * 会超过扫描限制 — 总是按分区列过滤(通常是 _PARTITIONDATE)

让信任级别较低的分析师探索数据而不读取 PII 行

👤 数据平台团队 ⏱ ~30 min advanced

何时使用: 你想通过聊天向更多人开放 BQ 访问权限,但又不想让他们能够读取客户邮箱。

步骤
  1. 配置受限字段
    在 config.json 中添加条目限制 users.emailusers.phoneusers.ssn 字段。Agent 只能聚合这些字段,不能直接 SELECT。✓ 已复制
    → 配置已生效
  2. 测试
    运行 SELECT email FROM users LIMIT 10。验证被阻止。然后运行 SELECT domain, COUNT(*) FROM users GROUP BY domain —— 验证正常工作。✓ 已复制
    → 阻止直接读取;允许聚合操作

结果: LLM 时代更安全的自助分析。

注意事项
  • 基于正则表达式的字段检测可能会错过复杂的别名 SQL — 深层防护 —— 也要使用 BQ 列级安全性 / 授权视图
搭配使用: gateway

自动从 BQ 编译日报表指标摘要

👤 PM、创始人 ⏱ ~30 min intermediate

何时使用: 你想每天早上在 Slack 中看到 KPI,不需要 BI 工具。

步骤
  1. 定义指标
    定义查询:DAU、注册数、收入、前 3 个错误。每个都包含昨日和 7 日均值。✓ 已复制
    → 每个指标对应的 SQL
  2. 运行并格式化
    运行全部并格式化为可直接发送到 Slack 的摘要。包含周环比增长。✓ 已复制
    → 可直接发送到 Slack 的消息

结果: 日报表指标,无需付费 BI 工具。

搭配使用: notion

组合

与其他 MCP 搭配,撬动十倍杠杆

bigquery-server + notion

周报表 KPI 文档

运行我的周报表 KPI 查询,并在 'Metrics Weekly' 中创建一个 Notion 页面,包含结果和评论。✓ 已复制
bigquery-server + gateway

通过 mcp-gateway + Presidio 实现 PII 安全访问

将 BigQuery MCP 放在 mcp-gateway 后面配合 Presidio;验证结果中客户邮箱被脱敏。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
list_datasets 探索的第一步 free
list_tables dataset 浏览数据集 free
describe_table dataset, table 查询前 free
query sql: str, max_bytes?: int 主要读取工具;默认限制为 1GB 扫描 BQ on-demand: $6.25 per TB scanned

成本与限制

运行它的成本

API 配额
BigQuery 作业配额(非常充足)
每次调用 Token 数
查询结果可能很大 —— 总是使用 LIMIT 或聚合
费用
GCP 按扫描字节数收费(按需 $6.25/TB)。在 MCP 中配置扫描限制以设置上限。
提示
按分区过滤。对于繁忙事实表的全表扫描会产生真实成本。MCP 的字节限制是你的安全网。

安全

权限、密钥、影响范围

最小权限: bigquery.dataViewer + bigquery.jobUser 仅限于特定数据集
凭据存储: 服务账号 JSON 位于挂载路径中;永远不要提交
数据出站: 查询结果会发送到你的 LLM 提供商
切勿授予: 不要向 MCP 的服务账号授予 dataOwner / dataEditor 权限

故障排查

常见错误与修复

数据集上的 PERMISSION_DENIED

服务账号缺少 BQ Data Viewer 权限。gcloud projects add-iam-policy-binding ...

验证: gcloud bigquery datasets list
查询超过配置的字节限制

添加分区过滤或列投影;或者如果确实需要,可以提高限制。

受限字段仍然出现在结果中

正则表达式匹配可能会错过别名列 —— 使用 BQ 授权视图以实现强隔离。

替代方案

mcp-bigquery-server 对比其他方案

替代方案何时用它替代权衡
Looker / Metabase你需要 BI 工具,而不是聊天更好的仪表板;交互性较弱
postgres MCP via Cloud SQL你的分析数据在 Postgres 中不同的引擎;Postgres 在大规模聚合上的扩展性不如 BQ

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills