BigQuery MCP 服务器

简介

BigQuery MCP 服务器是一个用于大型语言模型（LLMs）访问 Google BigQuery 的数据服务器。本文档将详细介绍该服务器的功能、安装步骤、配置方法以及使用示例。

功能

• 查询工具: 支持执行 SQL 查询，并返回结果。
• 列出所有数据集工具: 返回指定项目中的所有数据集。
• 列出所有表工具: 根据指定的数据集 ID，返回该数据集下的所有表。
• 获取表信息工具: 根据指定的数据集和表格 ID，返回表的元数据以及可选的分区信息。
• 预估查询工具: 预估执行查询的成本，包括处理的字节数和估算的费用。

安装步骤

1. 克隆仓库

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

2. 安装依赖

   使用 npm 或 yarn 进行安装：

   npm install
   # 或者
   yarn install
   

3. 构建项目

   npm run build
   # 或者
   yarn build
   

4. 启动服务器

   构建完成后，运行主文件以启动服务器：

   node dist/index.js
   

配置

环境变量

在 src/utils/args-parser.ts 中定义了以下环境变量：

• BIGQUERY_PROJECT_ID: Google Cloud 项目 ID（必填）
• BIGQUERY_KEY_FILE: 服务账户密钥文件路径（可选）
• BIGQUERY_LOCATION: BigQuery 地理位置（默认：asia-northeast1）

配置文件

可以在根目录下创建一个 .env 文件，内容如下：

BIGQUERY_PROJECT_ID=your_project_id
BIGQUERY_KEY_FILE=/path/to/service-account-key.json
BIGQUERY_LOCATION=asia-northeast1

工具使用示例

查询工具

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

列出所有数据集工具

// 无参数要求

列出所有表工具

{
  "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              # 入口文件
├── server.ts             # BigQueryMcpServer 类
├── types.ts              # 类型定义
├── tools/                # 工具实现
│   ├── query.ts          # 查询工具
│   ├── list-datasets.ts  # 列出所有数据集工具
│   ├── list-tables.ts    # 列出所有表工具
│   ├── table-info.ts     # 获取表信息工具
│   └── dry-run.ts        # 预估查询工具
└── utils/                # 工具函数
    ├── args-parser.ts    # 命令行参数解析器
    └── query-utils.ts    # 查询验证和响应格式化

许可证

MIT