BigQuery MCP Server

BigQuery MCP 服务

用于访问 Google BigQuery 的 Model Context Protocol（MCP）服务。此服务可帮助大语言模型（LLM）了解 BigQuery 数据集结构并执行 SQL 查询。

功能

身份验证和连接管理

• 支持应用默认凭据（ADC）或服务账号密钥文件
• 可配置项目 ID 和位置设置
• 启动时验证身份验证

工具

1. query

   • 执行只读（SELECT）BigQuery SQL 查询
   • 可配置最大结果数和计费字节数
   • 安全检查可阻止非 SELECT 查询

2. list_all_datasets

   • 列出项目中的所有数据集
   • 返回数据集 ID 数组

3. list_all_tables_with_dataset

   • 列出特定数据集中的所有表及其架构
   • 需要 datasetId 参数
   • 返回表 ID、架构、时间分区信息和说明

4. get_table_information

   • 获取表架构和示例数据（最多 20 行）
   • 支持带分区筛选条件的分区表
   • 对未使用筛选条件查询分区表的情况发出警告

5. dry_run_query

   • 检查查询有效性并估算费用，但不执行查询
   • 返回处理的数据量和预估费用

安全功能

• 仅允许 SELECT 查询（只读访问）
• 默认将查询处理上限设为 500GB，以防止产生过高费用
• 为分区表提供分区筛选条件建议
• 安全处理身份验证凭据

安装

本地安装

# Clone the repository
git clone https://github.com/yourusername/bigquery-mcp-server.git
cd bigquery-mcp-server

# Install dependencies
bun install

# Build the server
bun run build

# Install command to your own path.
cp dist/bigquery-mcp-server /path/to/your_place

Docker 安装

你也可以在 Docker 容器中运行此服务：

# Build the Docker image
docker build -t bigquery-mcp-server .

# Run the container
docker run -it --rm \
  bigquery-mcp-server \
  --project-id=your-project-id

或者使用 Docker Compose：

# Edit docker-compose.yml to set your project ID and other options
# Then run:
docker-compose up

MCP 配置

要将此服务与支持 MCP 的大模型搭配使用，请将其添加到 MCP 配置中：

{
  "mcpServers": {
    "BigQuery": {
      "command": "/path/to/dist/bigquery-mcp-server",
      "args": [
        "--project-id",
        "your-project-id",
        "--location",
        "asia-northeast1",
        "--max-results",
        "1000",
        "--max-bytes-billed",
        "500000000000"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account-key.json"
      }
    }
  }
}

你也可以使用应用默认凭据，而不是服务账号密钥文件：

{
  "mcpServers": {
    "BigQuery": {
      "command": "/path/to/dist/bigquery-mcp-server",
      "args": [
        "--project-id",
        "your-project-id",
        "--location",
        "asia-northeast1",
        "--max-results",
        "1000",
        "--max-bytes-billed",
        "500000000000"
      ]
    }
  }
}

设置应用默认凭据

使用应用默认凭据进行身份验证：

1. 如果尚未安装 Google Cloud SDK，请先安装：

   # For macOS
   brew install --cask google-cloud-sdk
   
   # For other platforms, see: https://cloud.google.com/sdk/docs/install
   

2. 运行身份验证命令：

   gcloud auth application-default login
   

3. 按照提示，使用有权访问 BigQuery 项目的 Google 账号登录。

4. 凭据将保存到本地计算机，并由 BigQuery MCP 服务自动使用。

测试

你可以使用 inspector 进行测试和调试。

npx @modelcontextprotocol/inspector dist/bigquery-mcp-server --project-id={{your_own_project}}

使用方法

使用辅助脚本

随附的 run-server.sh 脚本可让你轻松使用常见配置启动服务：

# Make the script executable
chmod +x run-server.sh

# Run with Application Default Credentials
./run-server.sh --project-id=your-project-id

# Run with a service account key file
./run-server.sh \
  --project-id=your-project-id \
  --location=asia-northeast1 \
  --key-file=/path/to/service-account-key.json \
  --max-results=1000 \
  --max-bytes-billed=500000000000

手动执行

你也可以直接运行编译后的二进制文件：

# Run with Application Default Credentials
./dist/bigquery-mcp-server --project-id=your-project-id

# Run with a service account key file
./dist/bigquery-mcp-server \
  --project-id=your-project-id \
  --location=asia-northeast1 \
  --key-file=/path/to/service-account-key.json \
  --max-results=1000 \
  --max-bytes-billed=500000000000

示例客户端

examples 目录中包含一个 Node.js 客户端示例：

# Make the example executable
chmod +x examples/sample-query.js

# Edit the example to set your project ID
# Then run it
cd examples
./sample-query.js

命令行选项

• --project-id：Google Cloud 项目 ID（必需）
• --location：BigQuery 位置（默认值：asia-northeast1）
• --key-file：服务账号密钥文件的路径（可选）
• --max-results：返回的最大行数（默认值：1000）
• --max-bytes-billed：要处理的最大字节数（默认值：500000000000，即 500GB）

所需权限

服务账号或用户凭据应具有以下任一权限：

• roles/bigquery.user（推荐）

或者同时具有以下两项权限：

• roles/bigquery.dataViewer（用于读取表数据）
• roles/bigquery.jobUser（用于执行查询）

使用示例

Query 工具

{
  "query": "SELECT * FROM `project.dataset.table` LIMIT 10",
  "maxResults": 100
}

列出所有数据集工具

// No parameters required

列出指定数据集中的所有表工具

{
  "datasetId": "your_dataset"
}

获取表信息工具

{
  "datasetId": "your_dataset",
  "tableId": "your_table",
  "partition": "20250101"
}

试运行查询工具

{
  "query": "SELECT * FROM `project.dataset.table` WHERE date = '2025-01-01'"
}

错误处理

服务会针对以下情况提供详细的错误消息：

• 身份验证失败
• 权限问题
• 无效查询
• 缺少分区筛选条件
• 请求处理的数据量过大

代码结构

服务的组织结构如下：

src/
├── index.ts              # Entry point
├── server.ts             # BigQueryMcpServer class
├── types.ts              # Type definitions
├── tools/                # Tool implementations
│   ├── query.ts          # query tool
│   ├── list-datasets.ts  # list_all_datasets tool
│   ├── list-tables.ts    # list_all_tables_with_dataset tool
│   ├── table-info.ts     # get_table_information tool
│   └── dry-run.ts        # dry_run_query tool
└── utils/                # Utility functions
    ├── args-parser.ts    # Command line argument parser
    └── query-utils.ts    # Query validation and response formatting

许可证

MIT