此页面由 Cloud Translation API 翻译。

将 BigQuery 与 MCP、Gemini CLI 和其他代理搭配使用

本指南介绍了如何使用 MCP Toolbox for Databases 将 BigQuery 项目连接到各种集成开发环境 (IDE) 和开发者工具。它使用 Model Context Protocol (MCP)，这是一种开放协议，用于将大语言模型 (LLM) 连接到 BigQuery 等数据源，让您能够直接通过现有工具运行 SQL 查询并与项目互动。

如果您使用 Gemini CLI，则可以使用 BigQuery 扩展程序。如需了解具体方法，请参阅使用 Gemini CLI 进行开发。如果您计划为 Gemini CLI 构建自定义工具，请继续阅读。

本指南演示了适用于以下 IDE 的连接过程：

光标
Windsurf（以前称为 Codeium）
Visual Studio Code (Copilot)
Cline（VS Code 扩展程序）
Claude Desktop
Claude Code

准备工作

在 Google Cloud 控制台的项目选择器页面上，选择或创建 Google Cloud 项目。
确保您的 Google Cloud 项目已启用结算功能。
在 Google Cloud 项目中启用 BigQuery API。
配置完成此任务所需的角色和权限。您需要拥有 BigQuery User 角色 (roles/bigquery.user)、BigQuery Data Viewer 角色 (roles/bigquery.dataViewer) 或等效的 IAM 权限才能连接到项目。
为您的环境配置应用默认凭证 (ADC)。

安装 MCP Toolbox

如果您只打算使用 BigQuery Gemini CLI 扩展程序，则无需安装 MCP Toolbox，因为这些扩展程序捆绑了所需的服务器功能。对于其他 IDE 和工具，请按照本部分中的步骤安装 MCP Toolbox。

该工具箱充当位于 IDE 和 BigQuery 之间的开源 Model Context Protocol (MCP) 服务器，为 AI 工具提供安全高效的控制平面。

以二进制文件形式下载最新版本的 MCP Toolbox。选择与您的操作系统 (OS) 和 CPU 架构对应的二进制文件。您必须使用 MCP Toolbox V0.7.0 版或更高版本：
linux/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/linux/amd64/toolbox
将 VERSION 替换为 MCP Toolbox 版本，例如 v0.7.0。
macOS darwin/arm64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/arm64/toolbox
将 VERSION 替换为 MCP Toolbox 版本，例如 v0.7.0。
macOS darwin/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/amd64/toolbox
将 VERSION 替换为 MCP Toolbox 版本，例如 v0.7.0。
windows/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/windows/amd64/toolbox
将 VERSION 替换为 MCP Toolbox 版本，例如 v0.7.0。
将该二进制文件设为可执行文件：
```
chmod +x toolbox
```
验证安装：
```
./toolbox --version
```

设置客户端和连接

本部分介绍了如何将 BigQuery 连接到您的工具。

如果您使用的是独立版 Gemini CLI，则无需安装或配置 MCP Toolbox，因为扩展程序会捆绑所需的服务器功能。

对于其他兼容 MCP 的工具和 IDE，您必须先安装 MCP Toolbox。

Claude Code

安装 Claude Code。
在项目根目录中创建 .mcp.json 文件（如果尚不存在）。

添加配置，将环境变量替换为您的值，然后保存：

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

重启 Claude Code 以加载新设置。重新打开该工具后，其会指示已检测到配置的 MCP 服务器。

Claude Desktop

打开 Claude Desktop，然后前往设置。
在开发者标签页中，点击修改配置以打开配置文件。

添加配置，将环境变量替换为您的值，然后保存：

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

重启 Claude Desktop。
新聊天界面会显示锤子 (MCP) 图标以及新的 MCP 服务器。

Cline

在 VS Code 中打开 Cline 扩展程序，然后点按 MCP 服务器图标。
点按配置 MCP 服务器以打开配置文件。

添加以下配置，将环境变量替换为您的值，然后保存：

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

服务器成功连接后，系统会显示绿色的活跃状态。

光标

在项目根目录中创建 .cursor 目录（如果尚不存在）。
创建 .cursor/mcp.json 文件（如果尚不存在）并打开该文件。

添加以下配置，将环境变量替换为您的值，然后保存：

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

打开 Cursor，然后依次前往设置 > Cursor 设置 > MCP。服务器连接时，系统会显示绿色的活跃状态。

Visual Studio Code (Copilot)

打开 VS Code，并在项目根目录中创建 .vscode 目录（如果尚不存在）。
创建 .vscode/mcp.json 文件（如果尚不存在）并打开该文件。

添加以下配置，将环境变量替换为您的值，然后保存：

        {
          "servers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

重新加载 VS Code 窗口。兼容 MCP 的扩展程序会自动检测配置并启动服务器。

Windsurf

打开 Windsurf 并前往 Cascade 助理。
点击 MCP 图标，然后点击配置以打开配置文件。

添加以下配置，将环境变量替换为您的值，然后保存：

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

注意：BIGQUERY_PROJECT 环境变量用于指定 MCP Toolbox 将使用的默认 Google Cloud 项目的 ID。所有 BigQuery 操作（例如执行查询）都在此项目中运行。

使用这些工具

您的 AI 工具现在已使用 MCP 连接到 BigQuery。尝试让 AI 助理列出表、创建表或定义和执行其他 SQL 语句。

LLM 可使用以下工具：

analyze_contribution：执行贡献分析（也称为关键驱动因素分析）。
ask_data_insights：执行数据分析、获取分析洞见，或回答有关 BigQuery 表内容的复杂问题。
execute_sql：执行 SQL 语句。
forecast：预测时序数据。
get_dataset_info：获取数据集元数据。
get_table_info：获取表元数据。
list_dataset_ids：列出数据集。
list_table_ids：列出表。
search_catalog：使用自然语言搜索表格。

将 BigQuery 与 MCP、Gemini CLI 和其他代理搭配使用

准备工作

安装 MCP Toolbox

linux/amd64

macOS darwin/arm64

macOS darwin/amd64

windows/amd64

设置客户端和连接

Claude Code

Claude Desktop

Cline

光标

Visual Studio Code (Copilot)

Windsurf

使用这些工具