bigquery-mcp

Snow Leopard BigQuery MCP

适用于 Google BigQuery 的模型上下文协议（MCP）服务，可让 AI Agent 通过自然语言查询和架构探索与 BigQuery 数据库交互。

本项目由 Snow Leopard AI 开发，作为我们平台的基准测试工具，并向公众开放，供社区使用和拓展。

什么是 MCP？

模型上下文协议（MCP）是一种开放标准，可让 AI 应用安全地连接到外部数据源和工具。此 BigQuery MCP 服务充当 AI Agent 与 BigQuery 数据集之间的桥梁。

Snow Leopard BigQuery MCP 服务功能

资源

资源 URI	描述
bigquery://tables	列出 Agent 可用的所有表
bigquery://tables/{table}/schema	获取指定表的架构

工具

工具	描述
list_tables(table: str)（可选）	列出可用的表
get_schema(table: str)（可选）	获取指定表的架构
query(sql: str)	执行 BigQuery SQL 并返回结果

快速开始：Claude Desktop

前提条件

开始之前，请确保你已准备好：

• Claude Desktop：点击此处下载
• 已启用 BigQuery 的 Google Cloud 项目：设置指南
• Google Cloud CLI（gcloud）：安装指南
• UV 包管理器：安装指南

1. 设置 Google Cloud

首先，我们需要通过 Google 进行身份验证。

gcloud auth application-default login

这会在浏览器中打开页面，以便使用 Google Cloud 对本地计算机进行身份验证。

2. 配置 Claude Desktop

编辑 claude_desktop_config.json 文件，添加 BigQuery MCP 服务。

应用程序：Claude > Settings > Developer > Edit Config
Mac：~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\\Claude\\claude_desktop_config.json

你需要将项目设置为具有提交 BigQuery 作业权限的 Google Cloud 项目。如果你没有可用于运行 BigQuery 作业的项目，请按照 Google 的 BigQuery 快速入门指南 创建并测试一个项目。创建项目后，按照说明查询公共数据集。

{
  "mcpServers": {
    "bigquery": {
      "command": "uvx",
      "args": [
        "sl-bigquery-mcp", 
        "--dataset",
        "bigquery-public-data.usa_names",
        "--project",
        "🚨 <projectName> 🚨"
      ]
    }
  }
}

3. 关闭 Claude Desktop 并从终端启动

根据 uv 的安装方式，如果从 GUI 启动 Claude Desktop，uvx 可执行文件可能不在其 PATH 中。为确保 Claude Desktop 可以访问 uvx，请从终端运行它。

open -a claude

保存配置后，重启 Claude Desktop。现在你应该可以向 Claude 询问 BigQuery 数据了！

查询示例

What are the top 10 most popular names in 2020?

配置选项

如需查看完整的参数列表：

uvx sl-bigquery-mcp --help

Usage: sl-bigquery-mcp [OPTIONS]

╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --mode                       [stdio|sse|streamable-http]  MCP transport protocol [default: stdio]                                                     │
│ --dataset                    TEXT                         Dataset(s) for mcp resources. Will create resources for all tables.                         │
│ --table                      TEXT                         Table(s) for mcp resources. Can be specified as project.dataset.table or dataset.table      │
│ --enable-list-tables-tool    --no-enable-list-tables-tool Registers list_resources tool [default: enable-list-tables-tool]                            │
│ --enable-schema-tool         --no-enable-schema-tool      Registers get_schema tool [default: enable-schema-tool]                                     │
│ --project                    TEXT                         BigQuery project [env var: BQ_PROJECT] [default: None]                                      │
│ --api-method                 [INSERT|QUERY]               BigQuery client api_method [default: QUERY]                                                 │
│ --port                       INTEGER                      [default: 8000]                                                                             │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

故障排除 / 常见问题

发生 MCP 错误

首先，查看 Claude Desktop 应用日志（与配置文件位于同一目录），以获取更详细的错误信息 / 日志。

启动时

这通常表示 Claude 无法启动 MCP 服务。常见原因是应用无法访问 uvx。此时，请在 claude_desktop_config.json 中使用 uvx 可执行文件的完整路径，而不是只写 uvx。

如需查找 uv 可执行文件，请运行

which uvx

否则，问题可能由参数错误、依赖版本不兼容或错误导致。如果遇到后两种情况，请提交 问题 并描述问题。

使用资源 / 工具时

这可能是 MCP 服务配置错误、身份验证问题、大模型接收的数据过多，当然也可能是产品错误。查看日志后，可以考虑使用 MCP Inspector 调试问题。当然，发现任何错误都请提交到我们的问题板。

本地开发与测试

设置开发环境

1. 克隆仓库
2. 设置虚拟环境并安装依赖项
3. 验证安装

git clone https://github.com/SnowLeopard-AI/bigquery-mcp.git
cd bigquery-mcp

uv sync
source .venv/bin/activate

sl-bigquery-mcp --help

使用 Google Cloud 进行身份验证

以下命令会启动浏览器，让你登录 Google Cloud 账号。你必须有一个已启用 BigQuery 的 Google Cloud 项目。如果没有，请参阅 Google 的 BigQuery 设置指南。

gcloud auth application-default login
gcloud config set project <projectName>
gcloud auth application-default set-quota-project <projectName>

运行测试

运行测试，确保开发环境配置正确。

pytest tests

注意：测试会针对公开数据集运行实际的 BigQuery 查询，并且需要进行身份验证。

本地 MCP Inspector

如需动手测试和开发，请使用 MCP Inspector 工具：

npx @modelcontextprotocol/inspector uv run sl-bigquery-mcp --dataset bigquery-public-data.usa_names

贡献

欢迎贡献！请先在 discord 上与我们协调，确保你的更改能尽快合并到仓库中。 编码前先沟通总能节省时间。

有关如何为开源项目做贡献的流程，请参阅 first contributions 仓库。

支持

问题：GitHub Issues
文档：BigQuery 文档
MCP 协议：Model Context Protocol
联系：Discord 服务器