AI导哈

BigQuery自然语言查询服务

一个基于Model Context Protocol (MCP)的服务器，使AI代理能够通过自然语言查询和模式探索与Google BigQuery数据库进行交互。

  • by SnowLeopard-AI
  • Python
  • 本地部署
  • 10 星标
  • 更新于
在 GitHub 查看 SnowLeopard-AI/bigquery-mcp

使用说明

Snow Leopard BigQuery MCP




一个针对Google BigQuery的模型上下文协议（MCP）服务器，它使AI代理能够通过自然语言查询和模式探索与BigQuery数据库进行交互。

这个项目由Snow Leopard AI开发，作为我们平台的基准测试工具，现在我们将其公开，供社区使用并在此基础上进行拓展。

什么是MCP？

这个（或：那个） 模型上下文协议 (MCP) 是一种开放标准，允许人工智能（AI）应用程序安全地连接到外部数据源和工具。这个 BigQuery MCP 服务器充当了 AI 代理与您的 BigQuery 数据集之间的桥梁。

Snow Leopard BigQuery MCP服务器特性

资源

资源URI 描述
bigquery://tables 列出代理可用的所有表
bigquery://tables/{table}/schema 获取特定表的模式（结构）

工具

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

快速入门：Claude 桌面版

先决条件

在开始之前，请确保您已具备：

  • Claude Desktop（可译为“Claude桌面版”或保持原样，若“Desktop”在此处作为产品或版本名称的一部分，则直接翻译为“桌面版”即可，整体保持为“Claude桌面版”）: 在此下载
  • 谷歌云项目 启用BigQuery后： 设置指南
  • Google Cloud 命令行界面 (gcloud)： 安装指南
  • UV 包管理器： 安装指南

1. 设置Google Cloud（谷歌云）

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

gcloud auth application-default login

这将打开您的浏览器，以便使用Google Cloud对您的本地机器进行身份验证。

2. 配置Claude桌面版

编辑你的 claude_desktop_config.json 文件用于添加BigQuery MCP服务器。

应用Claude > 设置 > 开发者 > 编辑配置
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桌面应用并从终端启动它

根据你安装uv的方式，如果从（某个位置）启动，uvx可执行文件可能不在Claude Desktop的环境变量PATH中 图形用户界面（GUI）。为了确保uvx可以从Claude Desktop访问，我们将在终端中运行它。

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桌面应用程序日志（位于配置文件的同一目录下），以获取更详细的错误信息/日志记录

在启动时

这通常意味着克劳德在启动MCP服务器时遇到了问题。这通常是由于无法从（某处）访问uvx所导致的 应用程序。在这种情况下，请使用您的uvx可执行文件的完整路径，而不是仅使用 uvx 在 claude_desktop_config.json.

要找到你的uv可执行文件，请运行

which uvx

否则，这可能会 由错误的参数、依赖版本不兼容或错误（bug）引起。如果你遇到了后两种情况，请提交一个（问题报告） 问题 描述问题。

关于资源/工具的使用

这可能是MCP服务器的配置错误、身份验证问题、大型语言模型（LLM）接收了过多数据，或者当然，也可能是产品问题 错误。检查日志后，考虑使用 MCP Inspector（中文可译为“MCP检查器”或根据具体语境调整为更贴切的名称） to 调试你的问题。当然，如果你发现了任何错误，请在我们的（平台上）报告 问题看板。

本地开发与测试

设置开发环境

  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账户。您必须拥有一个Google Cloud账户 与……一起的项目 BigQuery 已启用。如果您未启用，请参阅谷歌的（相关说明/指南） BigQuery 设置指南.

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

运行测试

运行测试以确保您的开发环境已正确配置。

pytest tests

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

当地MCP（可能是指某种特定机构或职位，如“市场协调员”、“管理控制点”等，具体需根据上下文确定）检查员

对于实际测试和开发，请使用 MCP 检查员 工具：

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

做出贡献

我们欢迎投稿！请与我们协调 Discord（一个即时通讯及视频聊天软件） 以确保您的更改能够快速合并到仓库中。 在编写代码之前先进行沟通，总是能节省时间。

关于为开源项目做贡献的物流事宜，请参阅 首个贡献仓库。

支持

问题: GitHub Issues（在GitHub上的问题/议题）
文档: BigQuery 文档
MCP协议： 模型上下文协议
联系： Discord 服务器

相关 MCP