Google BigQuery的MCP服务器

一种模型上下文协议（MCP）服务器，提供查询Google BigQuery数据库的工具。此服务器使AI助手能够与包含客户、人员、组织、潜在客户和产品数据的BigQuery数据集进行交互。

演示

Demo

🚀 运输方式

此服务器支持两种传输模式，可用于不同的MCP客户端：

标准输入/输出 -适用于Claude Desktop和VS Code

- 直接过程沟通 - 设置更简单，不需要服务器进程 - 推荐用于大多数用例

HTTP/SSE（服务器发送事件） -用于web客户端和远程连接

- 基于网络的通信 - 支持多个同时运行的客户端 - 需要单独运行服务器

特性

查询多个表：从客户、人员、组织、领导和产品表中访问数据
灵活过滤：使用WHERE子句筛选数据
自定义查询：对数据集执行自定义SQL查询
架构信息：获取表架构和列详细信息
可配置限制：控制返回的行数

先决条件

Node.js（v18或更高版本）
启用BigQuery的谷歌云平台帐户
具有BigQuery访问权限的服务帐户凭据
npm或yarn包管理器

安装

cd mcp-server-google-bigquery

安装依赖项：

npm install

创建 .env 文件（复制自 .env.example):

copy .env.example .env

更新 .env 使用您的Google Cloud凭据文件：

GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json
GOOGLE_CLOUD_PROJECT=your-gcp-project-id
DATASET=CUSTOMERS

# HTTP Server Configuration (optional, for HTTP/SSE mode)
PORT=3000
HOST=localhost

构建TypeScript代码：

npm run build

配置

环境变量

GOOGLE_APPLICATION_CREDENTIALS：您的Google Cloud服务帐户JSON密钥文件的路径
GOOGLE_CLOUD_PROJECT：您的Google Cloud项目ID
DATASET：包含表的BigQuery数据集名称

服务帐户权限

确保您的服务帐户具有以下权限：

bigquery.jobs.create
bigquery.tables.getData
bigquery.tables.get

用法

选项1:VS代码（推荐）

VS Code使用stdio传输 .vscode/mcp.json 配置文件。

第一步： 创建 .vscode/mcp.json 在您的工作空间中：

{
  "servers": {
    "bigquery": {
      "command": "node",
      "args": ["build/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "C:\\Users\\YourName\\path\\to\\service-account-key.json",
        "GOOGLE_CLOUD_PROJECT": "your-gcp-project-id",
        "DATASET": "CUSTOMERS"
      }
    }
  },
  "inputs": []
}

第二步： 构建项目：

npm run build

步骤3： 重新加载VS代码窗口(Ctrl+Shift+P → “开发人员：重新加载窗口”）

步骤4： 打开GitHub Copilot聊天，问：“有哪些MCP服务器可用？”

选项2：克劳德桌面

将此配置添加到您的Claude Desktop配置文件中：

视窗: %APPDATA%\Claude\claude_desktop_config.json\ macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\ Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bigquery": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-google-bigquery/build/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
        "GOOGLE_CLOUD_PROJECT": "your-gcp-project-id",
        "DATASET": "CUSTOMERS"
      }
    }
  }
}

注：在Windows上使用绝对路径和双反斜杠。

选项3:HTTP/SSE模式（Web客户端）

对于基于web的客户端或远程连接：

第一步： 启动HTTP服务器：

npm run start:http

第二步： 服务器将在 http://localhost:3000/sse

健康检查：

curl http://localhost:3000/health

答复：

{
  "status": "ok",
  "name": "mcp-server-google-bigquery",
  "version": "1.0.0"
}

可用工具

所有7个工具都可以在stdio和HTTP/SSE模式下使用：

1. `query_customers`

使用可选筛选器查询CUSTOMERS表。

参数：

limit （数字，可选）：要返回的最大行数（默认值：100）
whereClause （字符串，可选）：用于筛选的SQL WHERE子句
columns （字符串，可选）：逗号分隔的列名（默认值：\*）

示例：

"Get 10 customers from USA"
"Query customers where City = 'New York' limit 20"
"Show me all customers with columns: First_Name, Last_Name, Email"

2. `query_people`

使用可选筛选器查询PEOPLE表。

参数：

limit （数字，可选）：要返回的最大行数（默认值：100）
whereClause （字符串，可选）：SQL WHERE子句
columns （字符串，可选）：逗号分隔的列名（默认值：\*）

示例：

"Find all people with job title containing 'Manager'"
"Get people where Sex = 'Female' and Job_Title LIKE '%Engineer%'"
"Show first 50 people"

3. `query_organizations`

使用可选筛选器查询ORGANIONS表。

参数：

limit （数字，可选）：要返回的最大行数（默认值：100）
whereClause （字符串，可选）：SQL WHERE子句
columns （字符串，可选）：逗号分隔的列名（默认值：\*）

示例：

"Get organizations in the Technology industry"
"Find organizations where Country = 'USA' and Number_of_employees > 100"
"List all organizations founded after 2010"

4. `query_leads`

使用可选筛选器查询LEADS表。

参数：

limit （数字，可选）：要返回的最大行数（默认值：100）
whereClause （字符串，可选）：SQL WHERE子句
columns （字符串，可选）：逗号分隔的列名（默认值：\*）

示例：

"Find qualified leads from the website source"
"Get leads where Deal_Stage = 'Proposal' limit 25"
"Show all leads assigned to John Smith"

5. `query_products`

使用可选筛选器查询PRODUCTS表。

参数：

limit （数字，可选）：要返回的最大行数（默认值：100）
whereClause （字符串，可选）：SQL WHERE子句
columns （字符串，可选）：逗号分隔的列名（默认值：\*）

示例：

"Get products in Electronics category under $1000"
"Find products where Brand = 'Sony' and Availability = 'In Stock'"
"Show me all products with Price > 500"

6. `execute_custom_query`

对数据集执行自定义SQL查询以进行复杂分析。

参数：

query （string，必填）：要执行的完整SQL查询

示例：

-- Count customers by country
SELECT Country, COUNT(*) as total 
FROM `your-gcp-project-id.CUSTOMERS.CUSTOMERS` 
GROUP BY Country 
ORDER BY total DESC 
LIMIT 10

-- Analyze lead conversion by source
SELECT Source, Deal_Stage, COUNT(*) as count 
FROM `your-gcp-project-id.CUSTOMERS.LEADS` 
GROUP BY Source, Deal_Stage
ORDER BY count DESC

-- Product revenue analysis
SELECT Category, 
       COUNT(*) as product_count, 
       AVG(Price) as avg_price,
       SUM(Stock) as total_stock
FROM `your-gcp-project-id.CUSTOMERS.PRODUCTS` 
GROUP BY Category

7. `get_table_schema`

获取任何表的架构信息和列详细信息。

参数：

tableName （string，必填）：客户、人员、组织、领导、产品之一

示例：

"Show me the schema for CUSTOMERS table"
"What columns are in the LEADS table?"
"Get table schema for PRODUCTS"

持微软签名的表模式

客户

索引
客户Id
首页_名称
姓氏_姓名
公司
城市
国家
电话_1
电话_2
电子邮件
订阅_日期
网站

人们

索引
用户Id
首页_名称
姓氏_姓名
性
电子邮件
电话
出生日期:
职位_标题

组织

索引
组织\_ Id
名字
网站
国家
描述
成立
工业
员工人数

引导

索引
帐户Id
Lead_所有者
首页_名称
姓氏_姓名
公司
电话_1
电话_2
电子邮件_1
电子邮件_2
网站
源
Deal_Stage
备注

产品

索引
名字
描述
品牌
类别
价格
货币
股票
欧洲商品编号
颜色
尺寸
可用性
内部ID

查询示例

自然语言查询（聊天中）

连接MCP服务器后，您可以自然地提问：

客户分析：

“我们在美国有多少客户？”
“按订阅日期显示前10名客户”
“查找所有拥有Gmail地址的纽约客户”

人事和人力资源查询：

“列出数据库中的所有管理员”
“1990年以后出生的人有多少？”
“显示所有软件工程师”

组织见解：

“哪些行业拥有最多的组织？”
“寻找员工人数超过500人的科技公司”
“列出过去5年内成立的所有组织”

潜在客户管理：

“显示网站上所有合格的潜在客户”
“每个交易阶段有多少线索？”
“查找分配给特定销售代表的潜在客户”

产品查询：

“每个类别产品的平均价格是多少？”
“给我看看缺货的产品”
“列出所有500美元以下的索尼产品”

直接SQL查询

分析-客户分布：

SELECT Country, COUNT(*) as customer_count
FROM `your-gcp-project-id.CUSTOMERS.CUSTOMERS`
GROUP BY Country
ORDER BY customer_count DESC
LIMIT 10

分析-潜在客户转化漏斗：

SELECT Deal_Stage, COUNT(*) as count,
       ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER(), 2) as percentage
FROM `your-gcp-project-id.CUSTOMERS.LEADS`
GROUP BY Deal_Stage
ORDER BY count DESC

分析-产品库存价值：

SELECT Category, 
       SUM(Stock * Price) as inventory_value,
       COUNT(*) as product_count
FROM `your-gcp-project-id.CUSTOMERS.PRODUCTS`
GROUP BY Category
ORDER BY inventory_value DESC

分析-组织规模分布：

SELECT 
  CASE 
    WHEN Number_of_employees < 50 THEN 'Small (1-49)'
    WHEN Number_of_employees < 250 THEN 'Medium (50-249)'
    ELSE 'Large (250+)'
  END as company_size,
  COUNT(*) as count
FROM `your-gcp-project-id.CUSTOMERS.ORGANIZATIONS`
GROUP BY company_size

发展

项目结构

mcp-server-google-bigquery/
├── src/
│   ├── index.ts          # Stdio transport (Claude Desktop)
│   └── index-http.ts     # HTTP/SSE transport (VS Code/Visual Studio)
├── build/                # Compiled JavaScript output
├── package.json          # Project dependencies
├── tsconfig.json         # TypeScript configuration
├── .env.example          # Environment variable template
├── .env                  # Your environment variables
└── README.md            # This file

建筑

npm run build

开发模式（带自动重建）

npm run dev

故障排除

VS代码问题

服务器未出现在Copilot聊天中：

确保 .vscode/mcp.json 存在于您的工作区根目录中
跑 npm run build 编译TypeScript
重新加载VS代码窗口(Ctrl+Shift+P → “开发人员：重新加载窗口”）
检查输出面板(View → Output)从下拉菜单中选择“MCP”
验证mcp.json中的路径是否正确（在Windows上使用带有双反斜杠的绝对路径）

“正在等待服务器响应初始化请求”：

生成文件夹可能丢失-运行 npm run build
检查Node.js是否在您的系统PATH中
验证mcp.json中的环境变量是否正确
在VS Code的输出面板（MCP部分）中查找错误

未加载环境变量：

环境变量必须在 env 对象在 .vscode/mcp.json
不要依赖 .env VS代码的文件-它不会自动加载
使用带有正确转义的绝对路径（Windows： C:\\Users\\...)

Claude桌面问题

服务器未连接：

验证配置文件路径是否适用于您的操作系统
在配置中使用绝对路径
Windows用户：在路径中使用双反斜杠： C:\\Users\\...
配置更改后重新启动Claude Desktop
检查Claude Desktop日志中的错误消息

身份验证错误

“无法加载凭据”：

核实一下 GOOGLE_APPLICATION_CREDENTIALS 指向有效的JSON密钥文件
确保文件路径是绝对的，而不是相对的
检查服务帐户密钥文件是否未被删除或移动
Windows：在路径中使用双反斜杠或正斜杠

“权限被拒绝”错误：

确保服务帐户具有BigQuery权限：

- bigquery.jobs.create - bigquery.tables.getData - bigquery.tables.get

检查项目ID是否与您的GCP项目匹配
验证您的GCP项目是否已启用计费

查询错误

“找不到表”：

验证表名是否正确：客户、人员、组织、领导、产品
检查BigQuery数据集中是否存在表
确保环境变量中的数据集名称与BigQuery数据集匹配

“无效语法”错误：

带空格的列名应使用下划线： First_Name 不 First Name
在WHERE子句中使用正确的SQL语法
字符串值必须在单引号中： Country = 'USA'
对于LIKE查询，请使用通配符： Job_Title LIKE '%Manager%'

连接问题

BigQuery API错误：

确认在GCP项目中启用了BigQuery API
检查与Google Cloud服务的网络连接
验证您的GCP项目是否已启用计费
检查以下位置的服务中断情况谷歌云状态

HTTP模式问题：

确保端口3000未被使用： netstat -ano | findstr :3000 （Windows）
检查防火墙设置是否允许本地主机连接
HTTP服务器必须正在运行： npm run start:http
验证服务器是否正在响应： curl http://localhost:3000/health

调试提示

启用详细日志记录：

检查VS代码输出面板(View → Output → 选择“MCP”）
对于HTTP模式，检查服务器运行的控制台输出
在终端中查找错误消息

独立测试BigQuery连接：

# Test with gcloud CLI
gcloud auth application-default login
gcloud bigquery query --use_legacy_sql=false "SELECT 1"

验证您的设置：

# Check Node version (should be 18+)
node --version

# Check if build exists
ls build/index.js

# Test environment variables
echo %GOOGLE_CLOUD_PROJECT%  # Windows
echo $GOOGLE_CLOUD_PROJECT   # Linux/Mac

运输方式

标准运输（推荐）

使用人： 克劳德桌面，VS代码
它是如何工作的： 将服务器作为子进程生成
赞成的意见：

- 简单配置 - 不需要单独的服务器进程 - 自动生命周期管理 - 直接、安全的通信

欺骗：

- 每个服务器实例一个客户端 - 仅限本地

从以下内容开始： 自动（由客户端生成）
配置： .vscode/mcp.json 或Claude配置

HTTP/SSE传输

使用人： Web客户端、远程连接、自定义集成
它是如何工作的： 服务器作为独立的HTTP服务运行
赞成的意见：

- 多个同时运行的客户端 - 跨网络工作 - 可以远程部署 - RESTful健康检查端点

欺骗：

- 需要手动管理服务器 - 附加网络层 - 需要为web客户端处理CORS

从以下内容开始： npm run start:http
端点： http://localhost:3000/sse

NPM脚本

# Build TypeScript to JavaScript
npm run build

# Run in stdio mode (for testing manually)
npm start

# Run in HTTP/SSE mode
npm run start:http

# Development mode with auto-rebuild
npm run dev

安全须知

关键安全实践

请勿提交敏感文件：

# Already in .gitignore:
.env                    # Contains your credentials
.vscode/mcp.json       # May contain credentials

凭证管理：

永远不要承诺你的 .env 文件或服务帐户JSON到版本控制
永远不要在源代码中硬编码凭据
保持你的 GOOGLE_APPLICATION_CREDENTIALS 将文件放在安全位置
使用具有最低所需权限的服务帐户
定期轮换凭证（建议每90天一次）
考虑在生产环境中使用Google Cloud Secret Manager

服务帐户权限（最小权限原则）：

Minimum required roles:
- roles/bigquery.dataViewer (to read table data)
- roles/bigquery.jobUser (to run queries)

OR these specific permissions:
- bigquery.jobs.create
- bigquery.tables.getData
- bigquery.tables.get

网络安全（HTTP模式）：

默认配置绑定到 localhost 仅
对于生产，使用具有有效证书的HTTPS
实现HTTP端点的身份验证/授权
使用环境特定 .env 文件
考虑在生产环境中使用反向代理（nginx、Apache）

代码安全：

检查WHERE子句以防止SQL注入
对自定义查询中的用户输入进行消毒
限制查询结果大小以防止数据泄露
监控BigQuery审核日志中的可疑活动
为异常查询模式设置警报

生产检查表：

\[\]服务帐户使用最小权限
\[\]凭据位于Secret Manager或类似文件中
\[\]HTTP模式已启用HTTPS
\[\]API访问需要身份验证
\[\]已配置速率限制
\[\]已启用审核日志记录
\[\]敏感数据已正确屏蔽/加密
\[\]已安排定期安全审计

支持

资源

常见用例

商业智能：

客户细分分析
销售渠道报告
产品库存管理
潜在客户转化跟踪

数据探索：

快速数据质量检查
通过自然语言进行即席分析
架构发现
样本数据检查

报告自动化：

通过聊天界面生成报告
导出外部工具的数据
实时监控关键绩效指标
自动化日常数据查询

性能提示

查询优化：

使用列选择而不是 SELECT * 在可能的情况下
添加适当的WHERE子句以尽早过滤数据
使用LIMIT限制结果集大小
考虑大型表的分区策略

成本管理：

BigQuery对扫描的数据收费
使用列选择来减小扫描大小
缓存常用查询
在GCP控制台中监控查询成本
设置账单提醒

贡献

欢迎投稿！请随时提交拉取请求或未决问题：

错误修正
新功能
文档改进
性能优化
额外的桌子支撑
增强的错误处理

更新日志

1.0.0版本（首次发布）

✅ 标准传输支持（克劳德桌面，VS代码）
✅ HTTP/SSE传输支持（web客户端）
✅ 7个BigQuery查询工具
✅ 支持5个表（客户、人员、组织、领导、产品）
✅ 自定义SQL查询执行
✅ 表架构检查
✅ 基于环境的配置
✅ TypeScript实现
✅ 全面的错误处理

许可证

MIT许可证-有关详细信息，请参阅许可证文件

______________________________________________________________________

注：这是一个非官方工具，不隶属于谷歌云或Anthropic，也不受其认可。

Google Bigquery

快速接入

详细介绍

Google BigQuery的MCP服务器

演示

🚀 运输方式

特性

先决条件

安装

配置

环境变量

服务帐户权限

用法

选项1:VS代码（推荐）

选项2：克劳德桌面

选项3:HTTP/SSE模式（Web客户端）

可用工具

1. query_customers

2. query_people

3. query_organizations

4. query_leads

5. query_products

6. execute_custom_query

7. get_table_schema

持微软签名的表模式

客户

人们

组织

引导

产品

查询示例

自然语言查询（聊天中）

直接SQL查询

发展

项目结构

建筑

开发模式（带自动重建）

故障排除

VS代码问题

Claude桌面问题

身份验证错误

查询错误

连接问题

调试提示

运输方式

标准运输（推荐）

HTTP/SSE传输

NPM脚本

安全须知

关键安全实践

支持

资源

常见用例

性能提示

贡献

更新日志

1.0.0版本（首次发布）

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. `query_customers`

2. `query_people`

3. `query_organizations`

4. `query_leads`

5. `query_products`

6. `execute_custom_query`

7. `get_table_schema`