大数据查询-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桌面
前提条件
在开始之前，请确保您拥有：
1. 设置Google云
首先，我们需要与Google进行身份验证。
gcloud auth application-default login
这将在浏览器中打开以验证您的本地机器与Google云。
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云项目。如果您没有可以运行BigQuery作业的项目，请按照Google的BigQuery快速入门指南创建并测试一个项目。
{
"mcpServers": {
"bigquery": {
"command": "uvx",
"args": [
"sl-bigquery-mcp",
"--dataset",
"bigquery-public-data.usa_names",
"--project",
"🚨 <projectName> 🚨"
]
}
}
}
3. 关闭Claude桌面并通过终端启动它
根据您的uv安装方式，如果从GUI启动，uvx可执行文件可能不在Claude桌面的PATH中。为了确保uvx可以从Claude桌面访问，让我们在终端中运行它。
open -a claude
保存配置后，重新启动Claude桌面。现在您应该能够向Claude询问有关您的BigQuery数据的问题！
示例查询
2020年最受欢迎的前10个名字是什么？
配置选项
要查看完整的参数列表：
uvx sl-bigquery-mcp --help
用法: sl-bigquery-mcp [选项]
╭─ 选项 ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --mode [stdio|sse|streamable-http] MCP传输协议 [默认: stdio] │
│ --dataset 文本 MCP资源的数据集。将为所有表创建资源。 │
│ --table 文本 MCP资源的表。可以指定为项目.数据集.表或数据集.表 │
│ --enable-list-tables-tool --no-enable-list-tables-tool 注册list_resources工具 [默认: enable-list-tables-tool] │
│ --enable-schema-tool --no-enable-schema-tool 注册get_schema工具 [默认: enable-schema-tool] │
│ --project 文本 BigQuery项目 [环境变量: BQ_PROJECT] [默认: None] │
│ --api-method [INSERT|QUERY] BigQuery客户端api_method [默认: QUERY] │
│ --port 整数 [默认: 8000] │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
故障排除 / 常见问题解答
发生了MCP错误
首先，检查Claude桌面应用日志（与配置文件在同一目录下），以获取更详细的错误信息 / 日志
启动时
这通常意味着Claude在启动MCP服务器时遇到了问题。通常是因为从应用程序无法访问uvx。在这种情况下，在claude_desktop_config.json中使用uvx可执行文件的完整路径而不是仅仅uvx。
要找到您的uv可执行文件，请运行
which uvx
否则，这可能是由于参数错误、依赖版本不兼容或错误。如果您遇到后两种情况，请报告一个问题，描述问题。
在资源/工具使用时
这可能是由于MCP服务器配置错误、认证问题、LLM接收过多数据，当然也可能是产品错误。检查日志后，考虑使用MCP Inspector来调试您的问题。当然，如果您发现任何错误，请在我们的问题板上报告。
本地开发与测试
设置开发环境
- 克隆仓库
- 设置虚拟环境并安装依赖项
- 验证安装
git clone https://github.com/SnowLeopard-AI/bigquery-mcp.git
cd bigquery-mcp
uv sync
source .venv/bin/activate
sl-bigquery-mcp --help
与Google云进行身份验证
以下命令将为您打开浏览器登录到您的Google云账户。您必须有一个启用了BigQuery的Google云项目。如果没有，请参阅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问题
文档: BigQuery文档
MCP协议: 模型上下文协议
联系: Discord服务器