BigQuery MCP 服务器

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

特征

身份验证和连接管理

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

工具

询问
- 执行只读 (SELECT) BigQuery SQL 查询
- 可配置最大结果数和计费字节数
- 安全检查以防止非 SELECT 查询
列出所有数据集
- 列出项目中的所有数据集
- 返回数据集 ID 数组
列出所有带有数据集的表
- 列出特定数据集中的所有表及其架构
- 需要 datasetId 参数
- 返回表 ID、模式、时间分区信息和描述
获取表信息
- 获取表架构和示例数据（最多 20 行）
- 支持带有分区过滤器的分区表
- 对没有过滤器的分区表进行查询时发出警告
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 的 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，请安装：
# For macOS brew install --cask google-cloud-sdk # For other platforms, see: https://cloud.google.com/sdk/docs/install
运行身份验证命令：
gcloud auth application-default login
按照提示使用有权访问 BigQuery 项目的 Google 帐户登录。
凭据将保存到您的本地机器并由 BigQuery MCP 服务器自动使用。

测试

您可以使用检查器进行测试和调试。

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": "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

执照

麻省理工学院

BigQuery MCP Server

Integrations