使用说明

项目简介

BigQuery MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在弥合大型语言模型 (LLM) 与 Google BigQuery 数据仓库之间的鸿沟。它允许 LLM 通过标准化的 MCP 协议，安全、高效地访问 BigQuery 中的数据，并执行 SQL 查询等操作。

主要功能点

数据访问能力： 提供多种工具，允许 LLM 查询 BigQuery 数据，获取数据集、表信息以及表结构和示例数据。
SQL 查询执行： 支持执行只读 (SELECT) SQL 查询，并可配置最大结果行数和最大计费字节数，防止成本超支。
查询安全保障： 仅允许执行 SELECT 查询，避免数据修改操作；可配置查询处理的最大字节数限制，并提供分区表的分区过滤建议。
成本预估： 提供 dry_run_query 工具，在不实际执行查询的情况下，检查查询的有效性并预估成本。
灵活的身份验证： 支持应用默认凭据 (ADC) 或服务帐户密钥文件进行身份验证，方便集成到不同的环境。
易于部署： 提供本地安装和 Docker 两种安装方式，方便用户快速部署和使用。
完善的错误处理： 提供详细的错误信息，帮助用户快速定位和解决问题，例如身份验证失败、权限问题、无效查询等。

安装步骤

本地安装：

克隆仓库:

git clone https://github.com/takuya0206/bigquery-mcp-server.git
cd bigquery-mcp-server

安装依赖:
```
bun install
```
构建服务器:
```
bun run build
```

安装命令行工具 (可选):

cp dist/bigquery-mcp-server /path/to/your_place

Docker 安装：

构建 Docker 镜像:

docker build -t bigquery-mcp-server .

运行 Docker 容器:

docker run -it --rm bigquery-mcp-server --project-id=your-project-id

或者使用 Docker Compose，请先编辑 'docker-compose.yml' 文件配置项目 ID 和其他选项，然后运行：

docker-compose up

服务器配置

要将 BigQuery MCP Server 集成到 MCP 客户端，您需要在客户端的 MCP 配置中添加以下服务器信息。以下是使用应用默认凭据 (ADC) 的配置示例：

{
  "mcpServers": {
    "BigQuery": { #  服务器名称，可以自定义
      "command": "/path/to/dist/bigquery-mcp-server", # BigQuery MCP Server 的启动命令，请替换为实际路径
      "args": [ # 启动参数
        "--project-id", # Google Cloud 项目 ID，必填
        "your-project-id", #  请替换为您的 Google Cloud 项目 ID
        "--location", # BigQuery 位置，可选，默认为 asia-northeast1
        "asia-northeast1", #  请替换为您的 BigQuery 位置，例如 us-central1
        "--max-results", #  查询结果最大返回行数，可选，默认为 1000
        "1000",
        "--max-bytes-billed", #  查询处理的最大字节数，可选，默认为 500GB (500000000000 字节)
        "500000000000"
      ]
    }
  }
}

如果您使用服务帐户密钥文件进行身份验证，请添加 'env' 字段配置 'GOOGLE_APPLICATION_CREDENTIALS' 环境变量：

{
  "mcpServers": {
    "BigQuery": { #  服务器名称，可以自定义
      "command": "/path/to/dist/bigquery-mcp-server", # BigQuery MCP Server 的启动命令，请替换为实际路径
      "args": [ # 启动参数
        "--project-id", # Google Cloud 项目 ID，必填
        "your-project-id", #  请替换为您的 Google Cloud 项目 ID
        "--location", # BigQuery 位置，可选，默认为 asia-northeast1
        "asia-northeast1", #  请替换为您的 BigQuery 位置，例如 us-central1
        "--max-results", #  查询结果最大返回行数，可选，默认为 1000
        "1000",
        "--max-bytes-billed", #  查询处理的最大字节数，可选，默认为 500GB (500000000000 字节)
        "500000000000"
      ],
      "env": { # 环境变量配置
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account-key.json" # 服务帐户密钥文件路径，请替换为实际路径
      }
    }
  }
}

请注意： 您需要将 '/path/to/dist/bigquery-mcp-server' 替换为 'bigquery-mcp-server' 可执行文件的实际路径，并将 'your-project-id'、'asia-northeast1' 和 '/path/to/service-account-key.json' 替换为您的实际配置。

基本使用方法

配置完成后，您可以使用 MCP 客户端调用 BigQuery MCP Server 提供的工具。以下是一些工具的调用示例 (假设您已经配置了名为 "BigQuery" 的 MCP 服务器):

query 工具 (执行 SQL 查询):

{
  "serverName": "BigQuery", #  您在 MCP 配置中设置的服务器名称
  "tool": "query", #  工具名称
  "parameters": {
    "query": "SELECT * FROM 'your-project-id.your_dataset.your_table' LIMIT 10", #  要执行的 SQL 查询，请替换为您的实际查询
    "maxResults": 100 #  可选，最大返回结果行数
  }
}

list_all_datasets 工具 (列出所有数据集):

{
  "serverName": "BigQuery", #  您在 MCP 配置中设置的服务器名称
  "tool": "list_all_datasets", #  工具名称
  "parameters": {} #  无参数
}

list_all_tables_with_dataset 工具 (列出数据集中的所有表):

{
  "serverName": "BigQuery", #  您在 MCP 配置中设置的服务器名称
  "tool": "list_all_tables_with_dataset", #  工具名称
  "parameters": {
    "datasetId": "your_dataset" #  要查询的数据集 ID，请替换为您的实际数据集 ID
  }
}

get_table_information 工具 (获取表信息):

{
  "serverName": "BigQuery", #  您在 MCP 配置中设置的服务器名称
  "tool": "get_table_information", #  工具名称
  "parameters": {
    "datasetId": "your_dataset", #  数据集 ID，请替换为您的实际数据集 ID
    "tableId": "your_table", #  表 ID，请替换为您的实际表 ID
    "partition": "20250101" #  可选，分区，例如 '20250101' 或 '2025-01-01'
  }
}

dry_run_query 工具 (Dry run 查询):

{
  "serverName": "BigQuery", #  您在 MCP 配置中设置的服务器名称
  "tool": "dry_run_query", #  工具名称
  "parameters": {
    "query": "SELECT * FROM 'your-project-id.your_dataset.your_table' WHERE date = '2025-01-01'" #  要 dry run 的 SQL 查询，请替换为您的实际查询
  }
}

请根据您的实际需求选择合适的工具，并参考仓库的 'README.md' 文件获取更详细的工具参数和使用说明。

关键词