内容
# mcp-bigquery
<div align="center">
<img src="docs/assets/images/logo.png" alt="MCP BigQuery Logo" width="200">
**通过模型上下文协议实现安全的 BigQuery 探索**
[](LICENSE)
[](https://pypi.org/project/mcp-bigquery/)
[](https://pypi.org/project/mcp-bigquery/)
[](https://pypi.org/project/mcp-bigquery/)
[**文档**](https://caron14.github.io/mcp-bigquery/) |
[**快速开始**](#-快速开始) |
[**示例**](#-使用示例)
</div>
---
## 概述
mcp-bigquery 是一个模型上下文协议（MCP）服务器，允许 AI 助手（如 Claude）安全地与 Google BigQuery 进行交互。
### 主要功能
* **安全执行**：所有操作都严格限制在干预验证。服务器永远不会执行可能改变数据或产生执行成本的查询。
* **成本透明度**：在执行前提供查询成本和处理字节的估计。
* **静态分析**：分析查询依赖关系并验证 SQL 语法。
* **模式探索**：浏览数据集、表格和列。
### 商业价值
| 问题 | mcp-bigquery 解决方案 |
|---------|---------------------------|
| 无意执行昂贵的查询 | 执行前成本估算 |
| 由于 SQL 语法错误导致的开发延迟 | 早期语法错误检测 |
| 缺乏对模式结构的可见性 | 安全的模式元数据发现 |
| AI 存在修改数据的风险 | 强制干预约束 |
---
## 快速开始
### 步骤 1：安装
通过 pip 安装软件包：
```bash
pip install mcp-bigquery
```
### 步骤 2：身份验证
设置 Google Cloud Platform 身份验证：
```bash
# 用户账户身份验证
gcloud auth application-default login
# 服务账户身份验证
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
```
### 步骤 3：Claude Desktop 配置
在 Claude Desktop 配置文件中配置服务器：
* **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
添加以下条目：
```json
{
"mcpServers": {
"mcp-bigquery": {
"command": "mcp-bigquery",
"env": {
"BQ_PROJECT": "your-gcp-project-id"
}
}
}
}
```
### 步骤 4：验证
重启 Claude Desktop 并运行以下查询以验证设置：
* "我的 BigQuery 项目中有哪些可用的数据集？"
* "您可以估算以下查询的成本：SELECT * FROM dataset.table"
* "显示 users 表的模式"
---
## 可用工具
### SQL 验证和分析
| 工具 | 目的 | 主要用例 |
|------|---------|------------------|
| **bq_validate_sql** | 检查 SQL 语法 | 查询执行前验证 |
| **bq_dry_run_sql** | 获取成本估算和元数据 | 执行前成本评估 |
| **bq_extract_dependencies** | 映射表依赖关系 | 血缘和依赖关系映射 |
| **bq_validate_query_syntax** | 详细语法分析 | 调试复杂 SQL 查询 |
### 模式发现
| 工具 | 目的 | 主要用例 |
|------|---------|------------------|
| **bq_list_datasets** | 列出项目中的所有数据集 | 初始项目发现 |
| **bq_list_tables** | 列出具有分区元数据的表 | 数据集结构浏览 |
| **bq_describe_table** | 获取详细的模式详细信息 | 列级验证 |
| **bq_get_table_info** | 获取综合元数据 | 表统计分析 |
| **bq_preview_table** | 预览表数据（免费） | 在不产生数据扫描成本的情况下检查样本记录 |
> [!IMPORTANT]
> **bq_preview_table** 工具使用 `client.list_rows`（API：`tabledata.list`）直接检索样本行，从而导致零字节被扫描且无执行成本。为防止敏感信息（如 PII）意外暴露给 LLM，此工具默认禁用。您必须通过在环境配置中设置 `MCP_BQ_ENABLE_PREVIEW=true` 来显式启用它。
---
## 配置
### 环境变量
| 变量 | 目的 | 默认值 |
|----------|---------|---------|
| `BQ_PROJECT` | 目标 GCP 项目 ID | 通过 ADC 确定 |
| `BQ_LOCATION` | 目标 BigQuery 区域 | 未设置 |
| `SAFE_PRICE_PER_TIB` | 成本估算的每 TiB 价格 | 5.0 |
| `LOG_LEVEL` | 日志详细程度（DEBUG, INFO, WARNING, ERROR, CRITICAL） | WARNING |
| `MCP_BQ_ENABLE_PREVIEW` | 启用 bq_preview_table 工具（true/false） | false |
### 示例 .env 文件
对于本地测试或开发环境，您可以在 `.env` 文件中定义这些变量：
```env
BQ_PROJECT=your-gcp-project-id
BQ_LOCATION=asia-northeast1
SAFE_PRICE_PER_TIB=5.0
LOG_LEVEL=WARNING
MCP_BQ_ENABLE_PREVIEW=true
```
### 完整的 Claude Desktop 配置示例
```json
{
"mcpServers": {
"mcp-bigquery": {
"command": "mcp-bigquery",
"env": {
"BQ_PROJECT": "my-production-project",
"BQ_LOCATION": "asia-northeast1",
"SAFE_PRICE_PER_TIB": "6.0",
"LOG_LEVEL": "WARNING",
"MCP_BQ_ENABLE_PREVIEW": "true"
}
}
}
}
```
---
## 故障排除
### 错误映射和解决方案
#### 身份验证错误
```
错误：无法自动确定凭证
```
* **解决方案**：使用命令行重新身份验证：
```bash
gcloud auth application-default login
```
#### 权限被拒绝
```
错误：用户无 bigquery.tables.get 权限
```
* **解决方案**：向目标身份授予 `BigQuery 数据查看器` 角色：
```bash
gcloud projects add-iam-policy-binding YOUR_PROJECT \
--member="user:your-email@example.com" \
--role="roles/bigquery.dataViewer"
```
#### 缺少项目 ID
```
错误：需要项目 ID
```
* **解决方案**：确保在配置中正确设置了 `BQ_PROJECT` 变量。
---
## 使用示例
### 示例 1：运行前检查成本
```python
# 运行昂贵查询前...
query = "SELECT * FROM `bigquery-public-data.github_repos.commits`"
# 首先检查成本
result = bq_dry_run_sql(sql=query)
print(f"预估成本：${result['usdEstimate']}")
print(f"处理的数据：{result['totalBytesProcessed'] / 1e9:.2f} GB")
# 输出：
# 预估成本：$12.50
# 处理的数据：2500.00 GB
```
### 示例 2：了解表结构
```python
# 检查表模式
result = bq_describe_table(
dataset_id="your_dataset",
table_id="users"
)
# 输出：
# ├── user_id (INTEGER, REQUIRED)
# ├── email (STRING, NULLABLE)
# ├── created_at (TIMESTAMP, REQUIRED)
# └── profile (RECORD, REPEATED)
# ├── name (STRING)
# └── age (INTEGER)
```
### 示例 3：跟踪数据依赖关系
```python
# 了解查询依赖关系
query = """
WITH user_stats AS (
SELECT user_id, COUNT(*) as order_count
FROM orders
GROUP BY user_id
)
SELECT u.name, s.order_count
FROM users u
JOIN user_stats s ON u.id = s.user_id
"""
result = bq_extract_dependencies(sql=query)
# 输出：
# 表：['orders', 'users']
# 列：['user_id', 'name', 'id']
# 依赖关系图：
# orders → user_stats → final_result
# users → final_result
```
---
## 项目状态和版本历史
| 版本 | 发布日期 | 变更摘要 |
|---------|--------------|--------------------|
| v0.7.0 | 2026-06-21 | 添加免费表格预览工具（`bq_preview_table`）和安全启用配置 |
| v0.6.0 | 2026-06-21 | 线程安全缓存、递归 AST 查询、重试和 Google API 异常映射 |
| v0.5.0 | 2026-01-02 | 统一格式化器、客户端缓存和统一日志控制 |
| v0.4.2 | 2025-12-08 | 模块化模式浏览器和统一客户端/日志控制 |
| v0.4.1 | 2025-01-22 | 错误处理和调试日志改进 |
| v0.4.0 | 2025-01-22 | 添加模式发现工具 |
| v0.3.0 | 2025-01-17 | 集成 SQL 静态分析引擎 |
| v0.2.0 | 2025-01-16 | 支持基本验证和干预查询的初始发布 |
---
## 开发和贡献
有关本地开发设置和贡献策略的说明，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 指南。
```bash
# 克隆仓库
git clone https://github.com/caron14/mcp-bigquery.git
cd mcp-bigquery
# 安装开发依赖项
pip install -e ".[dev]"
# 执行测试套件
pytest tests/
```
---
## 许可证
该项目根据 MIT 许可证授权。有关详细信息，请参阅 [LICENSE](LICENSE)。
