使用说明

项目简介

该项目 'LucasHild_mcp-server-bigquery' 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为大型语言模型 (LLM) 提供访问 Google BigQuery 数据仓库的能力。通过该服务器，LLM可以利用预定义的工具，安全、可控地查询和分析BigQuery中的数据。

主要功能点

执行 SQL 查询 (execute-query): 允许LLM执行 BigQuery SQL 查询，并获取查询结果。
列出数据表 (list-tables): 允许LLM获取 BigQuery 数据库中所有可用的数据表列表。
描述数据表结构 (describe-table): 允许LLM获取指定数据表的结构信息（DDL），帮助LLM理解表Schema。

安装步骤

克隆仓库: 首先，你需要克隆该GitHub仓库到本地。

git clone https://github.com/MCP-Mirror/LucasHild_mcp-server-bigquery
cd LucasHild_mcp-server-bigquery

安装依赖: 确保你的环境中安装了 'uv' 包管理器 (仓库的 README 中使用了 'uv' 命令，你也可以使用 'pip'，但可能需要根据 'uv sync' 生成的 'requirements.txt' 文件手动安装依赖)。如果使用 'uv'，运行：
```
uv sync
```
或者，如果使用 'pip'，可以尝试运行：
```
pip install -r requirements.txt
```
如果 'requirements.txt' 不存在，可能需要先安装 'uv' 并运行 'uv sync' 生成。

服务器配置

MCP客户端（例如 Claude）需要配置才能连接到此MCP服务器。以下是配置示例，你需要根据你的实际情况修改占位符。

配置信息 (JSON 格式):

{
  "mcpServers": {
    "bigquery": {
      "command": "uv",
      "args": [
        "--directory",
        "{{PATH_TO_REPO}}",  //  替换为仓库在您本地文件系统中的路径，例如 "/path/to/LucasHild_mcp-server-bigquery"
        "run",
        "mcp-server-bigquery", //  执行的模块名，对应 __init__.py 中定义的 main 函数入口
        "--project",
        "{{GCP_PROJECT_ID}}", //  替换为你的 Google Cloud Project ID
        "--location",
        "{{GCP_LOCATION}}"   //  替换为你的 BigQuery 数据集所在的地理位置，例如 "europe-west9"
      ]
    }
  }
}

参数说明:

'"bigquery"': 服务器名称，客户端用此名称引用该服务器。
'"command": "uv"': 启动服务器的命令，这里使用 'uv' 运行器。如果你的环境配置不同，可能需要调整，例如直接使用 'python' 并指定 'main.py' 路径。
'"args"': 传递给启动命令的参数列表：
- '"--directory", "{{PATH_TO_REPO}}"': 指定仓库根目录，服务器代码在此目录下。
- '"run", "mcp-server-bigquery"': 使用 'uv run' 运行 'mcp_server_bigquery' 模块。
- '"--project", "{{GCP_PROJECT_ID}}"': 必需参数，指定要连接的 Google Cloud Project ID。
- '"--location", "{{GCP_LOCATION}}"': 必需参数，指定 BigQuery 数据集所在的地理位置。
- '"--dataset", "{{DATASET_NAME}}"' (可选，可重复多次): 可选参数，用于指定服务器只考虑特定的 BigQuery 数据集。如果不提供，服务器将考虑项目中的所有数据集。

注意:

请根据你的实际环境替换 '{{PATH_TO_REPO}}', '{{GCP_PROJECT_ID}}', 和 '{{GCP_LOCATION}}' 为正确的值。
如果你需要指定数据集过滤器，可以在 'args' 数组中添加 '"dataset"' 参数，例如 '"--dataset", "my_dataset_1"'. 可以重复添加 '--dataset' 参数来指定多个数据集。
确保你的环境已配置 Google Cloud SDK 和 BigQuery 访问权限，以便服务器能够成功连接到 BigQuery。

基本使用方法

按照上述 服务器配置 部分，配置你的 MCP 客户端（例如 Claude Desktop）。
启动 MCP 客户端。客户端将根据配置连接到该 BigQuery MCP 服务器。
在 MCP 客户端中，当需要访问 BigQuery 数据时，LLM 就可以调用该服务器提供的工具，例如：
- 使用 'execute-query' 工具执行 SQL 查询。
- 使用 'list-tables' 工具查看可用的数据表。
- 使用 'describe-table' 工具获取数据表结构信息。

LLM 将根据工具的描述和参数，生成相应的请求发送给 MCP 服务器，服务器执行操作并将结果返回给 LLM。

关键词