搭配使用 BigQuery 與 MCP、Gemini CLI 和其他代理程式

本指南說明如何使用 MCP Toolbox for Databases,將 BigQuery 專案連結至各種整合開發環境 (IDE) 和開發人員工具。這項工具採用模型上下文協定 (MCP),這是一項開放式協定,可將大型語言模型 (LLM) 連線至 BigQuery 等資料來源,讓您直接透過現有工具執行 SQL 查詢,並與專案互動。

如果使用 Gemini CLI,可以運用 BigQuery 擴充功能。如要瞭解如何使用,請參閱「使用 Gemini CLI 開發應用程式」。如要為 Gemini CLI 打造自訂工具,請繼續閱讀。

本指南將示範下列 IDE 的連線程序:

  • Cursor
  • Windsurf (原名 Codeium)
  • Visual Studio Code (Copilot)
  • Cline (VS Code 擴充功能)
  • Claude 電腦版
  • Claude 代碼

事前準備

  1. 在 Trusted Cloud 控制台的專案選擇器頁面中,選取或建立 Trusted Cloud by S3NS 專案。

  2. 確認您已為 Trusted Cloud 專案啟用計費功能

  3. 在 Trusted Cloud 專案中啟用 BigQuery API。

  4. 設定完成這項工作所需的角色和權限。如要連線至專案,您需要 BigQuery 使用者角色 (roles/bigquery.user)、BigQuery 資料檢視者角色 (roles/bigquery.dataViewer) 或同等 IAM 權限。

  5. 為環境設定應用程式預設憑證 (ADC)

安裝 MCP Toolbox

如果您只打算使用 BigQuery Gemini CLI 擴充功能,就不需要安裝 MCP Toolbox,因為這些擴充功能會一併提供必要的伺服器功能。如要使用其他 IDE 和工具,請按照本節的步驟安裝 MCP Toolbox。

這個工具箱是開放原始碼的模型上下文協定 (MCP) 伺服器,位於 IDE 和 BigQuery 之間,可為 AI 工具提供安全有效率的控制平面。

  1. 以二進位檔形式下載最新版 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

  2. 將二進位檔設為可執行檔:

    chmod +x toolbox
    
  3. 驗證安裝:

    ./toolbox --version
    

設定用戶端和連線

本節說明如何將 BigQuery 連線至工具。

如果您使用獨立的 Gemini CLI,則不需要安裝或設定 MCP 工具箱,因為擴充功能會將必要的伺服器功能封裝在一起。

如要使用其他與 MCP 相容的工具和 IDE,請先安裝 MCP Toolbox

Claude 代碼

  1. 安裝 Claude Code
  2. 在專案根目錄中建立 .mcp.json 檔案 (如果不存在)。
  3. 新增設定、將環境變數替換為您的值,然後儲存:
            {
              "mcpServers": {
                "bigquery": {
                  "command": "./PATH/TO/toolbox",
                  "args": ["--prebuilt","bigquery","--stdio"],
                  "env": {
                    "BIGQUERY_PROJECT": "PROJECT_ID"
                  }
                }
              }
            }
            
  4. 重新啟動 Claude Code,載入新設定。重新開啟時,工具會顯示已偵測到設定的 MCP 伺服器。

Claude 電腦版

  1. 開啟 Claude Desktop,然後前往「設定」
  2. 在「開發人員」分頁中,按一下「編輯設定」開啟設定檔。
  3. 新增設定、將環境變數替換為您的值,然後儲存:
            {
              "mcpServers": {
                "bigquery": {
                  "command": "./PATH/TO/toolbox",
                  "args": ["--prebuilt","bigquery","--stdio"],
                  "env": {
                    "BIGQUERY_PROJECT": "PROJECT_ID"
                  }
                }
              }
            }
            
  4. 重新啟動 Claude Desktop。
  5. 新的即時通訊畫面會顯示槌子 (MCP) 圖示和新的 MCP 伺服器。

Cline

  1. 在 VS Code 中開啟 Cline 擴充功能,然後輕觸「MCP Servers」圖示。
  2. 輕觸「設定 MCP 伺服器」,開啟設定檔。
  3. 新增下列設定,將環境變數替換為您的值,然後儲存:
            {
              "mcpServers": {
                "bigquery": {
                  "command": "./PATH/TO/toolbox",
                  "args": ["--prebuilt","bigquery","--stdio"],
                  "env": {
                    "BIGQUERY_PROJECT": "PROJECT_ID"
                  }
                }
              }
            }
            

伺服器連線成功後,狀態會顯示為綠色「有效」。

Cursor

  1. 在專案根目錄中建立 .cursor 目錄 (如果不存在)。
  2. 如果 .cursor/mcp.json 檔案不存在,請建立並開啟該檔案。
  3. 新增下列設定,將環境變數替換為您的值,然後儲存:
            {
              "mcpServers": {
                "bigquery": {
                  "command": "./PATH/TO/toolbox",
                  "args": ["--prebuilt","bigquery","--stdio"],
                  "env": {
                    "BIGQUERY_PROJECT": "PROJECT_ID"
                  }
                }
              }
            }
            
  4. 開啟「游標」,然後依序前往「設定」>「游標設定」>「MCP」。伺服器連線後,會顯示綠色的「有效」狀態。

Visual Studio Code (Copilot)

  1. 開啟 VS Code,並在專案根目錄中建立 .vscode 目錄 (如果不存在)。
  2. 如果 .vscode/mcp.json 檔案不存在,請建立並開啟該檔案。
  3. 新增下列設定,將環境變數替換為您的值,然後儲存:
            {
              "servers": {
                "bigquery": {
                  "command": "./PATH/TO/toolbox",
                  "args": ["--prebuilt","bigquery","--stdio"],
                  "env": {
                    "BIGQUERY_PROJECT": "PROJECT_ID"
                  }
                }
              }
            }
            
  4. 重新載入 VS Code 視窗。與 MCP 相容的擴充功能會自動偵測設定並啟動伺服器。

滑浪風帆

  1. 開啟 Windsurf,然後前往 Cascade 助理。
  2. 按一下 MCP 圖示,然後點選「設定」開啟設定檔。
  3. 新增下列設定,將環境變數替換為您的值,然後儲存:
            {
              "mcpServers": {
                "bigquery": {
                  "command": "./PATH/TO/toolbox",
                  "args": ["--prebuilt","bigquery","--stdio"],
                  "env": {
                    "BIGQUERY_PROJECT": "PROJECT_ID"
                  }
                }
              }
            }
            

注意:BIGQUERY_PROJECT 環境變數會指定 MCP 工具箱使用的預設 Trusted Cloud 專案 ID。所有 BigQuery 作業 (例如執行查詢) 都是在這個專案中執行。

使用工具

您的 AI 工具現在已透過 MCP 連線至 BigQuery。你可以要求 AI 助理列出資料表、建立資料表,或是定義及執行其他 SQL 陳述式。

LLM 可使用下列工具:

  • analyze_contribution:執行貢獻分析,也稱為主要驅動因素分析。
  • ask_data_insights:執行資料分析、取得洞察資訊,或回答有關 BigQuery 資料表內容的複雜問題。
  • execute_sql:執行 SQL 陳述式。
  • 預測:預測時間序列資料。
  • get_dataset_info:取得資料集中繼資料。
  • get_table_info:取得表格中繼資料。
  • list_dataset_ids:列出資料集。
  • list_table_ids:列出資料表。
  • search_catalog:使用自然語言搜尋資料表。