MCP Tools Reference: cloudcli.googleapis.com

工具：run_bq_command

執行單一 BigQuery CLI (bq) 指令。您可以使用這項工具在使用者專案中執行任何 bq 指令，包括建立、更新或刪除 GCP 資源的指令 (即突變)。

重要安全警告 (可能造成破壞)：這個工具可以建立、更新或刪除 BigQuery 資源 (例如 bq rm、bq cancel、bq query)，不限於唯讀指令。請務必謹慎使用。

禁止使用的指令：代理程式不得執行下列 bq 指令：bq init、bq pyshell、bq shell。

嚴格執行規則：

  1. 指令字串中必須至少指定 --project_id 或 --quota_project_id。
  2. 專案 ID 與配額專案：--project_id 旗標會指定指令執行的資源專案 (與 gcloud 的 --project 旗標相同)。--quota_project_id 標記會指定下游 BigQuery API 呼叫的帳單/配額費用所屬專案 (與 gcloud 的 --billing-project 標記相同)。如果指令中指定了 --project_id，系統會將其做為計費/配額專案。如未指定 --project_id 或另外指定 --quota_project_id，則帳單/配額專案會是 --quota_project_id 旗標中設定的專案。
  3. 旗標格式：所有長選項都必須使用「=」符號分隔旗標鍵和值。正確：'--project_id=my-project' 或 '--location=us'。錯誤：'--project_id my-project' 或 '--location us'。標記和值之間不得有空格。
  4. 沒有預設設定：bq 指令是以無狀態方式執行，不會載入 .bigqueryrc 等本機設定檔。因此，對於所有區域作業 (例如建立資料集或查詢區域資料集)，您「必須」明確指定 --location 旗標 (例如 --location=us 或 --location=EU)。
  5. 非同步作業：部分指令會啟動同步長時間執行的作業 (例如執行查詢工作)。您「應該」一律為這些指令傳遞 --nosync 標記，以免代理程式逾時。
  6. 指令限制：您「不得」使用下列 bq 指令：bq init、bq pyshell、bq shell。系統「不」支援指令管道或鏈結。
  7. 自我修正：如果指令傳回錯誤，請分析 stderr、修正語法或標記，然後在下一次疊代中重試。

變更 bq 指令的範例包括：bq mk、bq rm、bq update、bq insert、bq query (不含 --dry_run) 等。用法：RunBq(command="bq query --project_id=PROJECT_ID 'SELECT 1'", project="projects/PROJECT_ID", input_files=[{"path": "PATH", "contents": "CONTENTS"}]) 您必須在「command」參數中，以單一字串的形式提供完整的 bq 指令。您「必須」提供「project」參數 (格式：projects/PROJECT_ID) 做為帳單、API 啟用和配額消耗量檢查的 API 執行專案。

bq 指令/模式範例：

  1. 執行查詢：bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROMproject.dataset.tableLIMIT 10'
  2. 建立資料集：bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. 建立表格：bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. 移除資料集：bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. 移除表格：bq rm -f -t --project_id=PROJECT_ID myDataset.myTable
  6. 更新資料表說明：bq update --description="New description" --project_id=PROJECT_ID myDataset.myTable
  7. 列出專案中的資料集：bq ls --datasets=true --project_id=PROJECT_ID

下列程式碼範例說明如何使用 curl 呼叫 run_bq_command MCP 工具。

Curl 要求 
curl --location 'https://cloudcli.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "run_bq_command",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入內容的結構定義

RunBq 的要求訊息。

RunBqRequest

JSON 表示法 
{
  "project": string,
  "command": string,
  "inputFiles": [
    {
      object (File)
    }
  ]
}
欄位
project

string

這是必要旗標，專案，用於啟用 CloudCli API 的 API 和配額消耗。

格式必須為 projects/ 或 projects/
command

string

這是必要旗標，以單一字串執行的完整 bq 指令列。例如：「bq ls my-dataset --location=us」

系統會指示 LLM 對長時間執行的作業使用 --nosync 旗標，避免逾時。
inputFiles[]

object (File)

選用。供 bq 指令執行的檔案。

檔案

JSON 表示法 
{
  "path": string,
  "contents": string
}
欄位
path

string

這是必要旗標，檔案路徑 (相對於主目錄)。不得包含父項目錄遍歷 (..) 或殼層擴充功能。
contents

string

這是必要旗標，檔案內容。

輸出內容的結構定義

RunBq 的回應訊息。

RunBqResponse

JSON 表示法 
{
  "response": {
    object (CliExecutionResponse)
  },
  "outputFiles": [
    {
      object (File)
    }
  ]
}
欄位
response

object (CliExecutionResponse)

CLI 工具執行作業的回應，包含獨立的 stdout、stderr 串流和結束代碼。
outputFiles[]

object (File)

bq 指令執行時產生的檔案。

CliExecutionResponse

JSON 表示法 
{
  "stdout": string,
  "stderr": string,
  "exitCode": string
}
欄位
stdout

string

CLI 工具執行作業的 stdout 串流。
stderr

string

CLI 工具執行作業的 stderr 串流。
exitCode

string (int64 format)

CLI 工具執行的結束代碼。

檔案

JSON 表示法 
{
  "path": string,
  "contents": string
}
欄位
path

string

這是必要旗標，檔案路徑 (相對於主目錄)。不得包含父項目錄遍歷 (..) 或殼層擴充功能。
contents

string

這是必要旗標，檔案內容。

工具註解

破壞性提示：✅ | 等冪提示：❌ | 唯讀提示：❌ | 開放世界提示：❌