BigQuery MCP 服务器

适用于生产的MCP服务器，可安全、只读地访问Google BigQuery数据集。具备表级访问控制、查询成本估算、HTTP传输以及全面的安全验证功能。

📚 文档：

建筑学 - 系统设计与架构
WSL 设置指南 - Windows + WSL（Windows系统子系统）配置
Ngrok共享指南 - 与其他用户共享服务器

快速入门

1. 安装依赖项

pip install -r requirements.txt

2. 设置身份验证

对于公共数据集将您的服务帐户JSON文件放置在：

/mcp-gbq/service-account.json

如果该文件存在，服务器将自动使用它。

替代方法 （如果不使用service-account.json）：

# Option 1: Use your Google account
gcloud auth application-default login

# Option 2: Set environment variable
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

3. 运行服务器

HTTP 模式（默认 - 推荐用于部署）：

# Install HTTP dependencies
pip install fastapi uvicorn

# Run on default port 8000
python server.py

# Run on custom port
python server.py 8765

标准I/O模式（用于桌面代理集成）：

python server.py --stdio

Ngrok 模式（与他人共享）：

# Install ngrok support
pip install pyngrok

# Start server with ngrok
python server.py --ngrok

# Returns public URL like: https://abc123.ngrok-free.app
# Share this URL with anyone!

📖 书籍 看 docs/NGROK_SETUP.md 翻译为中文是：docs/NGROK设置指南.md 获取包含身份验证、监控和故障排除的完整ngrok指南。

连接到桌面代理

macOS/Linux

在您的桌面代理配置文件中添加：

macOS（发音为“Mac OS”，全称为“macintosh Operating System”，即苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bigquery": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-gbq/server.py", "--stdio"]
    }
  }
}

重启桌面代理。您应该会看到MCP服务器已连接，并有4个工具可用。

Windows + WSL（Windows Subsystem for Linux，即Windows上的Linux子系统）

📖 书籍看 docs/WSL_SETUP.md（文件名翻译为中文可表述为“文档/WSL设置指南.md”，但通常文件名保持原样，因为文件名本身不是句子或短语，而是标识符）完整的Windows + WSL配置指南。

快速配置：

{
  "mcpServers": {
    "bigquery": {
      "command": "wsl",
      "args": [
        "bash",
        "-c",
        "cd /home/YOUR_USERNAME/mcp-gbq && source venv/bin/activate && python server.py --stdio"
      ]
    }
  }
}

替换 YOUR_USERNAME 使用您的WSL用户名。

本地HTTP服务器

服务器默认以HTTP模式运行，用于本地测试和开发。

启动本地HTTP服务器

# Start HTTP server
python server.py 8000

# Test health endpoint
curl http://localhost:8000/health

# Access in browser
open http://localhost:8000

HTTP 端点

服务器提供了以下HTTP端点：

`GET /`

带有服务信息的根端点。

回答：

{
  "service": "BigQuery MCP Server",
  "status": "running",
  "endpoints": {
    "health": "/health",
    "mcp": "/mcp"
  }
}

`GET /health`

用于监控和负载均衡的健康检查端点。

回答：

{
  "status": "healthy",
  "service": "bigquery-mcp",
  "timestamp": "2025-10-22T08:46:24.271778Z"
}

用例：

容器健康检查（Docker、Kubernetes）
负载均衡器健康检查探针
监控系统（Prometheus、Datadog 等）
运行时间监控

`POST /mcp`

工具执行的MCP协议端点。

这是MCP客户端使用的主要端点，用于：

列出可用工具
执行查询
获取表模式
估算成本

注：此端点使用MCP协议，通常通过MCP客户端访问，而不是直接通过HTTP请求访问。

使用MCP Inspector进行测试

npx @modelcontextprotocol/inspector python server.py --stdio

可用工具

服务器提供了5种工具：

获取查询限制 - 查看当前查询限制和BigQuery配置
列出表（或“显示表列表”） - 查看所有可用的数据集和表格
获取表结构 - 查看表结构和字段类型
估计查询成本 - 估算查询成本而不实际执行（模拟运行）
bq_query（可译为“BQ查询”或根据上下文具体含义翻译，若“BQ”为特定系统或数据库名称，则保留原样） - 在允许的表上运行SELECT查询

可用资源

服务器公开了4个MCP资源，用于可浏览的数据发现：

`bigquery://tables`

列出您有权访问的所有可用表和模式。这将为您提供数据目录的快速概览。

`bigquery://table/{table_id}/schema`

获取特定表的详细模式信息，包括：

行数和表大小
创建和修改日期
字段名称、类型和描述
格式化为可读的Markdown表格

示例： bigquery://table/bigquery-public-data.iowa_liquor_sales.sales/schema

`bigquery://datasets`

浏览所有可访问的数据集及其配置：

可完全访问的数据集
单个表的权限
通配符模式
黑名单表格

`bigquery://limits`

查看当前的查询限制和配置：

每查询返回的最大结果数
计费限制
成本信息
如何调整设置

资源带来的益处：

📖 克劳德可以在不执行工具的情况下浏览并发现您的数据
🔍 自然数据探索与模式检查
💡 更好的查询生成上下文
⚡ 更快的响应速度（获取元数据无需执行工具）

安全特性

只读强制执行：

仅允许SELECT查询
块（或操作类型）：DELETE（删除）、UPDATE（更新）、INSERT（插入）、CREATE（创建）、DROP（删除表或数据库）、ALTER（修改）、MERGE（合并）、TRUNCATE（清空）、REPLACE（替换）、GRANT（授权）、REVOKE（撤销权限）
防止SQL注入和多语句攻击
在验证之前移除注释和字符串字面量
验证是否符合允许的表白名单

查询限制（可通过 .env)：

每个查询最多可获取10,000行（默认设置 - 已设定） MAX_QUERY_RESULTS （要）改变
每查询100 MB的计费限制（默认设置 - 已设定） MAX_BYTES_BILLED_MB （要改变）
表访问由……控制 access-control.json

验证示例：

✓ SELECT * FROM table WHERE name = 'DELETE'  -- String literals OK
✓ SELECT * FROM table /* comment */          -- Comments removed safely
✗ SELECT * FROM table; DROP TABLE users;     -- Multi-statement blocked
✗ DELETE FROM table                          -- Non-SELECT blocked

当前数据集

bigquery-public-data.iowa_liquor_sales.sales - 爱荷华州酒类零售销售
bigquery-public-data.austin_bikeshare.bikeshare_stations - 奥斯汀自行车站点
bigquery-public-data.austin_bikeshare.bikeshare_trips - 奥斯汀自行车旅行历史

如何使用

一旦连接到桌面代理，您就可以通过自然语言与BigQuery进行交互。Claude将自动使用MCP工具。

示例查询

列出可用的表：

You: What tables are available in BigQuery?
You: Show me what datasets I can query

探索表结构：

You: What's the schema for the Iowa liquor sales table?
You: Show me the fields in austin bikeshare trips
You: What columns are available in the bikeshare stations table?

估算查询成本：

You: How much will this query cost to run? SELECT * FROM `bigquery-public-data.iowa_liquor_sales.sales`
You: Estimate the cost of querying all Austin bike trips
You: What's the data size for this query?

查询数据：

You: Show me the top 10 liquor sales from Iowa
You: Which cities in Iowa have the highest liquor sales?
You: Get 5 recent bike trips from Austin
You: How many bike stations are there in each council district?
You: What's the average trip duration in the Austin bikeshare system?

复分析：

You: Analyze Iowa liquor sales by category and show trends
You: Compare bike usage patterns between different Austin neighborhoods
You: Find the busiest bike stations in Austin

示例对话

You: What datasets do I have access to?
Claude: [Uses list_tables and shows 3 available tables with descriptions]

You: Show me the schema for austin bikeshare trips
Claude: [Uses get_table_schema and displays field names, types, and metadata]

You: Get the top 5 most popular start stations
Claude: [Uses bq_query with SQL and presents results]

You: Now show me the average trip duration for each subscriber type
Claude: [Executes another query and analyzes the data]

直接SQL查询

你也可以直接编写SQL：

You: Run this query:
SELECT store_name, SUM(sale_dollars) as total
FROM `bigquery-public-data.iowa_liquor_sales.sales`
GROUP BY store_name
ORDER BY total DESC
LIMIT 10

高级功能

自动成本保护

所有查询首先都会自动进行预估成本的模拟运行！

服务器通过以下方式防止昂贵的查询：

在执行前进行预演以估算成本
将估算的字节与计费限制进行比较（默认为100 MB）
对于超出限制的查询要求用户确认

示例工作流程：

You: Query all Iowa liquor sales for the entire year
Claude: [Runs dry-run first]
Claude: ⚠️ This query will process 2.5 GB and cost approximately $0.0125.
       This exceeds the 100 MB limit. Do you want to proceed?

You: Yes, proceed
Claude: [Executes query with confirmed=True]
Claude: [Returns results with actual cost information]

成本估算包括：

待处理的字节
数据大小（以MB/GB为单位）
预估成本（以美元计，每TB 5美元）
与配置的限制进行比较

好处：

防止意外执行昂贵查询
用户在执行前总能了解成本
您的BigQuery账单中不会出现意外费用
确认后仍可运行大型查询

异步生命周期管理

服务器为BigQuery客户端生命周期使用了适当的异步上下文管理：

启动时自动建立连接
优雅地进行关闭时的清理工作
资源池化以提升性能

HTTP传输

使用HTTP传输运行服务器以进行本地访问或通过ngrok共享：

# Start HTTP server (local access)
python server.py 8000

# Share publicly via ngrok
python server.py --ngrok

# Access via HTTP endpoint
curl http://localhost:8000

用例：

本地测试与开发
通过ngrok与他人共享
通过Web应用程序访问

成本估算（模拟运行）

在执行前估算查询成本：

# Via Desktop Agent
You: "Estimate cost for: SELECT * FROM bigquery-public-data.iowa_liquor_sales.sales WHERE date > '2020-01-01'"

# Response includes:
# - Bytes to be processed
# - Estimated cost in USD
# - Data size in MB/GB

好处：

避免昂贵的查询
预算规划
查询优化

测试

运行所有测试

python tests/run_all_tests.py

预期输出：

Total Tests:     54
Passed:          54 ✓
Failed:          0
Pass Rate:       100.0%

🎉 All tests passed! 🎉

测试覆盖率

✅ SQL验证、功能及导入 - 共54项测试。详见 tests/README.md（文件名，可翻译为“测试/README.md”或保持原样，因为文件名通常不翻译）详情如下。

接下来是什么

添加更多数据集

编辑 access-control.json 添加更多表格或数据集：

{
  "allowed_tables": [
    "bigquery-public-data.iowa_liquor_sales.sales",
    "bigquery-public-data.dataset_name.table_name"
  ],
  "allowed_datasets": {
    "bigquery-public-data.austin_bikeshare": {
      "allow_all_tables": true,
      "blacklisted_tables": [],
      "description": "Austin bike sharing system"
    },
    "bigquery-public-data.dataset_name": {
      "allow_all_tables": true,
      "blacklisted_tables": ["sensitive_table"],
      "description": "Your dataset description"
    }
  },
  "allowed_patterns": [
    "bigquery-public-data.*"
  ]
}

浏览公共数据集：https://console.cloud.google.com/marketplace/browse?filter=solution-type:dataset

添加功能

潜在的改进之处：

查询结果缓存
每个用户的速率限制
查询历史记录日志
针对常见查询的自定义提示模板
支持参数化查询

故障排除

权限被拒绝错误

如果你看到“权限被拒绝”或“403”错误：

1. 检查您的服务账户是否拥有正确的角色：

您的服务帐户至少需要：

BigQuery User 角色（运行查询）
BigQuery Data Viewer 角色（读取数据）

在 Google Cloud Console 中：

进入 IAM 与管理 > 服务帐号
查找您的服务账户
点击“权限”选项卡
授予角色： BigQuery User 并且 BigQuery Data Viewer

2. 在您的项目中启用计费：

公共数据集可免费查询，但您仍需启用计费功能：

进入Google Cloud Console的账单页面
将计费账户链接到您的项目

3. 对于公开数据集：

如果查询公共数据集（如 bigquery-public-data.*)，您的服务帐户需要：

在您的项目（查询运行的地方）中，BigQuery 用户角色
在您的项目中已启用计费

你不需要在（该系统/设备上）拥有特殊权限 bigquery-public-data 项目。

4. 验证服务账户文件：

# Check service account file exists
ls -la /mcp-gbq/service-account.json

# Verify it's valid JSON
cat service-account.json | jq .project_id

表未找到错误

“表未找到”或“404”：

验证表ID是否正确： project.dataset.table
在BigQuery控制台检查表是否存在
确保表在允许列表中（使用 list_tables （用于验证）

查询错误

“超出预算”:

查询费用限制为100 MB
添加 LIMIT 减少扫描数据的条款
使用 WHERE 在扫描前过滤数据

连接错误：

重启桌面代理
检查WSL是否正在运行： wsl --status 在Windows中
验证Python和venv是否正常工作： wsl bash -c "cd /mcp-gbq && source venv/bin/activate && python --version"

测试您的设置

在WSL中运行此命令以测试身份验证：

cd ~/mcp-gbq
source venv/bin/activate
python -c "
from google.cloud import bigquery
import json

with open('service-account.json') as f:
    info = json.load(f)
    project = info['project_id']

client = bigquery.Client.from_service_account_json('service-account.json', project=project)
query = 'SELECT 1 as test'
result = list(client.query(query).result())
print(f'✓ Authentication works! Project: {project}')
print(f'✓ Test query result: {result}')
"

如果这个方法有效，那么MCP服务器也应该能正常工作。

gbq MCP

快速接入

详细介绍