JinDaGe - bigquery-mcp-server MCP Details

article

README

🚀 BigQuery MCP 服务器

BigQuery MCP 服务器是一个专门为大型语言模型（LLMs）访问 Google BigQuery 而设计的数据服务器。它能助力用户高效执行各类操作，如 SQL 查询、数据集和表的管理等。下面将详细介绍该服务器的各项功能、安装步骤、配置方法以及使用示例。

✨ 主要特性

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

📦 安装指南

克隆仓库

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

安装依赖 使用 npm 或 yarn 进行安装：
```
npm install
# 或者
yarn install
```
构建项目
```
npm run build
# 或者
yarn build
```
启动服务器 构建完成后，运行主文件以启动服务器：
```
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

错误处理

服务器提供详细的错误信息，包括：

认证失败
权限问题
查询语法错误
分区过滤器缺失
数据处理量过大请求

代码结构

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    # 查询验证和响应格式化

💻 使用示例

基础用法

查询工具

{
  "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'"
}

📄 许可证

MIT

bigquery-mcp-server