MCP 服务器

BigQuery MCP Server

一个模型上下文协议服务器，使大型语言模型能够理解 BigQuery 数据集结构并执行 SQL 查询。

README

BigQuery MCP 服务器

一个用于访问 Google BigQuery 的模型上下文协议 (MCP) 服务器。此服务器使大型语言模型 (LLM) 能够理解 BigQuery 数据集结构并执行 SQL 查询。

功能

身份验证和连接管理

支持应用程序默认凭据 (ADC) 或服务帐户密钥文件
可配置的项目 ID 和位置设置
启动时进行身份验证验证

工具

query
- 执行只读 (SELECT) BigQuery SQL 查询
- 可配置的最大结果数和计费字节数
- 安全检查以防止非 SELECT 查询
list_all_datasets
- 列出项目中的所有数据集
- 返回数据集 ID 数组
list_all_tables_with_dataset
- 列出特定数据集中的所有表及其模式
- 需要 datasetId 参数
- 返回表 ID、模式、时间分区信息和描述
get_table_information
- 获取表模式和示例数据（最多 20 行）
- 支持带有分区过滤器的分区表
- 对没有过滤器的分区表查询发出警告
dry_run_query
- 检查查询有效性并估算成本，无需执行
- 返回处理大小和估计成本

安全特性

仅允许 SELECT 查询（只读访问）
查询处理的默认限制为 500GB，以防止过度成本
分区表的推荐分区过滤器
安全处理身份验证凭据

安装

本地安装

# 克隆存储库
git clone https://github.com/yourusername/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 镜像
docker build -t bigquery-mcp-server .

# 运行容器
docker run -it --rm \
  bigquery-mcp-server \
  --project-id=your-project-id

或者使用 Docker Compose：

# 编辑 docker-compose.yml 以设置您的项目 ID 和其他选项
# 然后运行：
docker-compose up

MCP 配置

要将此服务器与启用 MCP 的 LLM 一起使用，请将其添加到您的 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"
      ]
    }
  }
}

设置应用程序默认凭据

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

如果您尚未安装 Google Cloud SDK，请安装它：

# 对于 macOS
brew install --cask google-cloud-sdk

# 对于其他平台，请参阅：https://cloud.google.com/sdk/docs/install

运行身份验证命令：
```
gcloud auth application-default login
```
按照提示使用有权访问 BigQuery 项目的 Google 帐户登录。
凭据将保存到您的本地计算机，并由 BigQuery MCP 服务器自动使用。

测试

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

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

用法

使用辅助脚本

包含的 run-server.sh 脚本可以轻松地使用常见配置启动服务器：

# 使脚本可执行
chmod +x run-server.sh

# 使用应用程序默认凭据运行
./run-server.sh --project-id=your-project-id

# 使用服务帐户密钥文件运行
./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

手动执行

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

# 使用应用程序默认凭据运行
./dist/bigquery-mcp-server --project-id=your-project-id

# 使用服务帐户密钥文件运行
./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 客户端：

# 使示例可执行
chmod +x examples/sample-query.js

# 编辑示例以设置您的项目 ID
# 然后运行它
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
}

List All Datasets 工具

// 无需参数

List All Tables With Dataset 工具

{
  "datasetId": "your_dataset"
}

Get Table Information 工具

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

Dry Run Query 工具

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

错误处理

服务器提供详细的错误消息，用于：

身份验证失败
权限问题
无效查询
缺少分区过滤器
过多的数据处理请求

代码结构

服务器组织成以下结构：

src/
├── index.ts              # 入口点
├── server.ts             # BigQueryMcpServer 类
├── types.ts              # 类型定义
├── tools/                # 工具实现
│   ├── query.ts          # query 工具
│   ├── list-datasets.ts  # list_all_datasets 工具
│   ├── list-tables.ts    # list_all_tables_with_dataset 工具
│   ├── table-info.ts     # get_table_information 工具
│   └── dry-run.ts        # dry_run_query 工具
└── utils/                # 实用函数
    ├── args-parser.ts    # 命令行参数解析器
    └── query-utils.ts    # 查询验证和响应格式化