BigQuery MCP 服务器
用于访问 Google BigQuery 的模型上下文协议 (MCP) 服务器。该服务器使大型语言模型 (LLM) 能够理解 BigQuery 数据集结构并执行 SQL 查询。
特征
身份验证和连接管理
工具
询问
列出所有数据集
列出所有带有数据集的表
列出特定数据集中的所有表及其架构
需要 datasetId 参数
返回表 ID、模式、时间分区信息和描述
获取表信息
获取表架构和示例数据（最多 20 行）
支持带有分区过滤器的分区表
对没有过滤器的分区表进行查询时发出警告
dry_run_query
无需执行即可检查查询有效性并估算成本
返回处理大小和估计成本
Related MCP server: mcp-graphql
安全功能
仅允许 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）
所需权限
服务帐户或用户凭据应具有以下之一：
或者以下两者：
示例用法
查询工具
{
"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
执照
麻省理工学院