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

本文說明如何將 Spanner 執行個體連線至支援模型上下文協定 (MCP) 的各種開發人員工具。

建議使用 Gemini CLI 專用的 Spanner 擴充功能。這項擴充功能會抽象化，因此您不需要設定個別的伺服器連線。您可以設定 Gemini Code Assist 使用 Gemini CLI，在 IDE 中享有類似的設定優點。詳情請參閱「Gemini CLI Extension - Spanner」。

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

在 Spanner 中使用 Gemini CLI 擴充功能

Spanner 與 Gemini CLI 的整合是透過開放原始碼擴充功能進行，與標準 MCP 工具箱連線相比，可提供額外功能。這個擴充功能提供安裝程序和一組工具，並詳細說明安裝、設定和使用範例。如果您使用 Gemini CLI 擴充功能，則不需要安裝 MCP Toolbox。詳情請參閱「Gemini CLI Extension - Spanner」。

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

工具 自然語言提示範例
list_tables 我的 Spanner 執行個體中有哪些資料表？
execute_sql 將測試資料插入產品資料表。
execute_sql_dql 美國銷售哪些電子產品？

事前準備

  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/genai-toolbox/version/linux/amd64/toolbox

    darwin/arm64

    curl -O https://storage.googleapis.com/genai-toolbox/version/darwin/arm64/toolbox

    darwin/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/version/darwin/amd64/toolbox

    windows/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/version/windows/amd64/toolbox

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

    chmod +x toolbox

  3. 驗證安裝：

    ./toolbox --version

設定代理程式工具

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

Gemini CLI

  1. 安裝 Gemini CLI。
  2. 使用下列指令，從 GitHub 存放區安裝 Gemini CLI 的 Spanner 擴充功能：
    3.   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 Code Assist

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


1. 在 VS Code 中安裝 Gemini Code Assist 擴充功能。
2. 啟用代理模式，並將代理模型切換為 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"
      }
    }
  }
}

採用 PostgreSQL 方言的 Spanner：

{
  "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. 如果專案根目錄中沒有 .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"
      }
    }
  }
}

採用 PostgreSQL 方言的 Spanner：

{
  "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


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"
      }
    }
  }
}

採用 PostgreSQL 方言的 Spanner：

{
  "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"
      }
    }
  }
}

採用 PostgreSQL 方言的 Spanner：

{
  "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"
      }
    }
  }
}

採用 PostgreSQL 方言的 Spanner：

{
  "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. 開啟「游標」，然後依序前往「設定」>「游標設定」>「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"
      }
    }
  }
}

採用 PostgreSQL 方言的 Spanner：

{
  "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"
      }
    }
  }
}

採用 PostgreSQL 方言的 Spanner：

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