搭配使用 Spanner 與 MCP Toolbox for Databases、Gemini CLI 和其他代理程式

本文說明如何將 Spanner 執行個體連線至支援 Model Context Protocol (MCP) 的各種開發人員工具。

建議使用 Gemini CLI 專用的 Spanner 擴充功能。擴充功能會將基礎技能直接綁定至擴充功能，簡化設定和配置程序。您可以設定 Gemini Code Assist 使用 Gemini CLI，在 IDE 中享有類似的設定優勢。詳情請參閱「Gemini CLI 擴充功能 - Spanner」。

或者，其他支援 MCP 的 IDE 和開發人員工具可以透過 MCP Toolbox for Databases 連線。MCP Toolbox 是開放原始碼的 MCP 伺服器，可將 AI 代理連結至您的資料。這項工具可處理驗證和連線集區等工作，讓您直接在 IDE 中以自然語言與資料互動。

在 Spanner 中使用 Gemini CLI 擴充功能

Spanner 與 Gemini CLI 的整合是透過開放原始碼擴充功能進行，與標準 MCP Toolbox 連線相比，這項擴充功能提供更多功能。這項擴充功能提供簡化的安裝程序，以及一組以 MCP 工具為基礎的技能。如果您使用 Gemini CLI 擴充功能，則無須安裝 MCP Toolbox。詳情請參閱「Gemini CLI 擴充功能 - Spanner」。

spanner 擴充功能包含列出資料表，以及執行 SQL 和 SQL DQL 陳述式的技能。

如要查看所有可用的技能，請參閱 GitHub 上的 Spanner 技能。

事前準備

  1. 在 Google Cloud 控制台的專案選擇器頁面中，選取或建立 Google Cloud 專案。

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

設定 Spanner 執行個體

  1. 在 Google Cloud 專案中啟用 Spanner API。

  2. 建立或選取 Spanner 執行個體和資料庫。

  3. 設定完成這項工作所需的角色和權限。呼叫 LLM 代理程式的使用者必須具備資料庫層級的下列角色：

    • Cloud Spanner 資料庫讀取者 (roles/spanner.databaseReader)：執行 DQL 查詢及列出資料表。

    • Cloud Spanner 資料庫使用者 (roles/spanner.databaseUser) 執行 DML 查詢。

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

安裝 MCP Toolbox

  1. 以二進位檔形式下載最新版 MCP Toolbox。選取與作業系統 (OS) 和 CPU 架構對應的二進位檔。您必須使用 MCP Toolbox 0.15.0 以上版本：

    linux/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/linux/amd64/toolbox

    darwin/arm64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/darwin/arm64/toolbox

    darwin/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/darwin/amd64/toolbox

    windows/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/windows/amd64/toolbox

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

    chmod +x toolbox

  3. 驗證安裝項目：

    ./toolbox --version

設定用戶端和連線

本節說明如何設定各種開發人員工具，以連線至 Spanner 執行個體。從下列選項中選取客戶：

Gemini CLI

  1. 安裝 Gemini CLI。
  2. 使用下列指令，從 GitHub 存放區安裝 Gemini CLI 的 Spanner 擴充功能：
    gemini extensions install https://github.com/gemini-cli-extensions/spanner
  3. 設定下列環境變數，連線至 Spanner 執行個體： 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     更改下列內容：
    • PROJECT_ID： Google Cloud 專案 ID。
    • INSTANCE_NAME：Spanner 執行個體名稱。
    • DATABASE_NAME：Spanner 資料庫名稱。
    • DIALECT_NAME：Spanner SQL 方言。接受 googlesql 或 postgresql。如未定義，預設為 googlesql。
  4. 在互動模式下啟動 Gemini CLI： 
    gemini

    CLI 會自動載入 Gemini CLI 適用的 Spanner 擴充功能及其技能，您可以使用這些功能與資料庫互動。

    在 Gemini CLI 中，使用 /extensions 指令驗證擴充功能是否已安裝。

Gemini Code Assist

強烈建議您將 Gemini Code Assist 設定為使用 Gemini CLI，因為這樣就不必手動設定 MCP 伺服器。不過，您還是可以參閱下列章節，瞭解如何手動設定 MCP 伺服器：


1. 在 VS Code 中安裝 Gemini Code Assist 擴充功能。
2. 啟用 Agent 模式，並將代理模型切換為 Gemini。
3. 在專案根目錄中，建立名為 .gemini 的資料夾，並在其中建立 settings.json 檔案。
4. 根據 settings.json 檔案中的 Spanner 方言，新增下列其中一種設定。
5. 將下列變數替換為您的值：
  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • INSTANCE_NAME：Spanner 執行個體名稱。
  • DATABASE_NAME：您的 Spanner 資料庫名稱。
6. 儲存檔案。

使用 GoogleSQL 方言的 Spanner：

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner (PostgreSQL 方言)：

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Claude Code

  1. 安裝 Claude Code。
  2. 設定環境變數，連線至 Spanner 執行個體： 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     更改下列內容：
    • PROJECT_ID： Google Cloud 專案 ID。
    • INSTANCE_NAME：Spanner 執行個體名稱。
    • DATABASE_NAME：Spanner 資料庫名稱。
    • DIALECT_NAME：Spanner SQL 方言。接受 googlesql 或 postgresql。如未定義，預設為 googlesql。
  3. 啟動代理： 
    claude
  4. 安裝外掛程式： 
    /plugin install spanner@claude-plugins-official

Codex

  1. 安裝 Data Cloud 外掛程式 Marketplace： 
    codex plugin marketplace add GoogleCloudPlatform/data-cloud-plugins
  2. 安裝 Spanner 外掛程式： 
    codex plugin install spanner@data-cloud-plugins
  3. 設定環境變數，連線至 Spanner 執行個體： 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     更改下列內容：
    • PROJECT_ID： Google Cloud 專案 ID。
    • INSTANCE_NAME：Spanner 執行個體名稱。
    • DATABASE_NAME：Spanner 資料庫名稱。
    • DIALECT_NAME：Spanner SQL 方言。接受 googlesql 或 postgresql。如未定義，預設為 googlesql。
  4. 選用。更新 Marketplace： 
    codex plugin marketplace upgrade data-cloud-plugins

Claude 電腦版


1. 開啟 Claude 電腦版，然後前往「設定」。
2. 在「開發人員」分頁中，按一下「編輯設定」開啟設定檔。
3. 根據 Spanner 方言新增下列其中一個設定，將環境變數替換為您的值，然後儲存檔案：

使用 GoogleSQL 方言的 Spanner：

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner (PostgreSQL 方言)：

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

4. 重新啟動 Claude 電腦版。
5. 新的即時通訊畫面會顯示槌子 (MCP) 圖示和新的 MCP 伺服器。

Cline


1. 在 VS Code 中開啟 Cline 擴充功能，然後按一下「MCP Servers」圖示。
2. 輕觸「設定 MCP 伺服器」開啟設定檔。
3. 根據 Spanner 方言新增下列其中一個設定，將環境變數替換為您的值，然後儲存檔案：

使用 GoogleSQL 方言的 Spanner：

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner (PostgreSQL 方言)：

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

伺服器連線成功後，會顯示綠色的有效狀態。

Cursor


1. 如果專案根目錄中沒有 .cursor 目錄，請建立該目錄。
2. 如果 .cursor/mcp.json 檔案不存在，請建立並開啟該檔案。
3. 根據 Spanner 方言新增下列其中一個設定，將環境變數替換為您的值，然後儲存檔案：

使用 GoogleSQL 方言的 Spanner：

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner (PostgreSQL 方言)：

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

4. 開啟 Cursor，然後依序前往「Settings」>「Cursor Settings」>「MCP」。伺服器連線時，會顯示綠色的「有效」狀態。

Visual Studio Code (Copilot)


1. 開啟 VS Code，並在專案根目錄中建立 .vscode 目錄 (如果不存在)。
2. 如果 .vscode/mcp.json 檔案不存在，請建立並開啟該檔案。
3. 根據 Spanner 方言新增下列其中一個設定，將環境變數替換為您的值，然後儲存檔案：

使用 GoogleSQL 方言的 Spanner：

{
  "servers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
        "SPANNER_PROJECT": "PROJECT_ID",
        "SPANNER_INSTANCE": "INSTANCE_NAME",
        "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner (PostgreSQL 方言)：

{
  "servers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
        "SPANNER_PROJECT": "PROJECT_ID",
        "SPANNER_INSTANCE": "INSTANCE_NAME",
        "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

風浪板


1. 開啟 Windsurf，然後前往 Cascade 助理。
2. 點按 MCP 圖示，然後點選「設定」開啟設定檔。
3. 根據 Spanner 方言新增下列其中一個設定，將環境變數替換為您的值，然後儲存檔案：

使用 GoogleSQL 方言的 Spanner：

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner (PostgreSQL 方言)：

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

連結至 Antigravity

您可以透過下列方式將 Spanner 連線至 Antigravity：

  • 使用 MCP 商店
  • 使用自訂設定

MCP 商店

最建議使用內建的 MCP 商店連線至 Antigravity。

  1. 開啟 Antigravity，然後開啟編輯器的代理程式面板。
  2. 按一下面板頂端的「選單」圖示，然後選取「MCP 伺服器」。
  3. 在可用伺服器清單中找出「Spanner」，然後點選「安裝」。
  4. 按照畫面上的步驟操作，授權 Antigravity 存取 Google Cloud 專案。這會授予 Antigravity 專案中 Spanner 執行個體的存取權。

在 MCP 商店中安裝 Spanner 伺服器後，編輯器就能使用伺服器的資源和技能。

自訂設定

如要連線至自訂 MCP 伺服器，請按照下列步驟操作：

  1. 開啟 Antigravity，然後開啟編輯器的代理程式面板。
  2. 按一下面板頂端的「選單」圖示，然後選取「MCP 伺服器」。
  3. 按一下「管理 MCP 伺服器」>「查看原始設定」，開啟 mcp_config.json 檔案。
  4. 新增下列設定，將環境變數替換為您的值，然後儲存。
{
  "mcpServers": {
    "spanner": {
      "command": "npx",
      "args": ["-y","@toolbox-sdk/server","--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME",
          "SPANNER_DIALECT": "DIALECT_NAME"
      }
    }
  }
}

設定自訂 MCP 伺服器後，編輯器就能使用 Spanner 伺服器的資源和技能。

更改下列內容：

  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • INSTANCE_NAME：Spanner 執行個體名稱。
  • DATABASE_NAME：您的 Spanner 資料庫名稱。
  • DIALECT_NAME：您的 Spanner SQL 方言。接受 googlesql 或 postgresql。如未指定方言，則預設為 googlesql。

使用 Data Agent Kit 連線至 Spanner

Google Cloud Data Agent Kit 可讓您管理 Spanner 資料庫，並在偏好的 IDE 或程式碼代理程式中，對 Spanner 資料執行查詢。Data Agent Kit 擴充功能適用於 Visual Studio Code 和以 VS Code 為基礎的 IDE，而 Data Agent Kit 外掛程式則適用於多種熱門程式設計代理，包括 Claude Code 和 Codex CLI。

Data Agent Kit 提供資料探索功能，可讓您以自然語言詢問有關 Spanner 資料的問題。可避免在 Spanner 指令列工具和開發環境之間切換。

詳情請參閱「Data Agent Kit 總覽」。