BigQuery MCP

BigQuery MCP服务器

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

特性

身份验证和连接管理

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

工具

1. 怎么翻译

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

1. list_all_datasets

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

1. list_all_tables_with_dataset

- 列出特定数据集中的所有表及其模式 - 需要datasetId参数 - 返回表ID、模式、时间分区信息和描述

1. 获取表格信息

- 获取表模式和示例数据（最多20行） - 支持带有分区过滤器的分区表 - 对没有筛选器的分区表进行查询的警告

1. 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"
      ]
    }
  }
}

设置应用程序默认凭据

要使用应用程序默认凭据进行身份验证，请执行以下操作：

1. 如果您还没有安装Google Cloud SDK，请安装：

   # For macOS
   brew install --cask google-cloud-sdk

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

1. 运行身份验证命令：

   gcloud auth application-default login

1. 按照提示使用有权访问BigQuery项目的Google帐户登录。

1. 凭据将保存到您的本地计算机，并由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

客户端示例

示例Node.js客户端包含在 examples 目录：

# 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：谷歌云项目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

许可证

麻省理工学院