Use Spanner with MCP Toolbox for Databases, Gemini CLI, and other agents

This document describes how to connect your Spanner instance tovarious developer tools that support theModel Context Protocol (MCP).

We recommend using the dedicated Spannerextension forGemini CLI.This extension abstracts away the need to set up a separate server connection.You can configure Gemini Code Assist to use the Gemini CLI,offering similar setup benefits in your IDE. For more information, seeGemini CLI Extension - Spanner.

Alternatively, other IDEs and developer tools supporting the MCP can connectthroughMCP Toolbox for Databases.MCP Toolbox is an open-source MCP server designed to connect AI agents toyour data. It handles tasks like authentication and connection pooling, lettingyou interact with your data with natural language directly from your IDE.

Use the Gemini CLI extension in Spanner

Note: MCP Toolbox for Databases is in beta (pre-v1.0), and may seebreaking changes until the first stable release. (v1.0)

The Spanner integration with Gemini CLI is through anopen-source extension that offers additional capabilities compared to thestandard MCP Toolbox connection. The extension offers an installation processand a set of tools, in addition to providing detailed information oninstallation, configuration, and usage examples. If you use theGemini CLI extension, you don't need to install MCP Toolbox. For moreinformation, seeGemini CLI Extension - Spanner.

Thespanner extension includes tools for listing tables, andexecuting SQL and SQL DQL statements.

ToolsExample natural language prompt
list_tablesWhat tables do I have in my Spanner instance?
execute_sqlInsert test data into the products table.
execute_sql_dqlWhat products in the electronics category are sold in America?

Before you begin

  1. In the Google Cloud console, on theproject selector page,select or create a Google Cloud project.

  2. Make sure that billing is enabled for your Google Cloud project.

Set up the Spanner instance

  1. Enable the Spanner API in the Google Cloud project.

  2. Create or select a Spanner instance and database.

  3. Configure the required roles and permissions to complete this task. The userinvoking the LLM agents needs the following roles at the database level:

    • Cloud Spanner Database Reader (roles/spanner.databaseReader) to execute DQL queries and list tables.

    • Cloud Spanner Database User (roles/spanner.databaseUser) to execute DML queries.

  4. ConfigureApplication Default Credentials (ADC) for your environment.

Install MCP Toolbox

Note: MCP Toolbox is only required for MCP clients other thanGemini CLI or Gemini Code Assist.Skip this section if you are using Gemini CLI orGemini Code Assist.

  1. Download the latest version of MCP Toolbox as a binary. Select thebinary corresponding to your operating system (OS) and CPU architecture. You must use MCP Toolbox version 0.15.0 or later:

    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. Make the binary executable:

    chmod+xtoolbox

  3. Verify the installation:

    ./toolbox--version

Set up the agent tool

This section describes how to configure various developer tools to connect toyour Spanner instance. Select your agent tool from thefollowing options:

Gemini CLI

  1. Install theGemini CLI.
  2. Install the Spanner extension for Gemini CLI from the GitHub repository using the following command:
    3.   gemini extensions install https://github.com/gemini-cli-extensions/spanner
  3. Set the following environment variables to connect to your Spanner instance:
        export SPANNER_PROJECT: "PROJECT_ID"    export SPANNER_INSTANCE: "INSTANCE_NAME"    export SPANNER_DATABASE: "DATABASE_NAME"    export SPANNER_DIALECT: "DIALECT_NAME"
     Replace the following:
    • PROJECT_ID: your Google Cloud project ID.
    • INSTANCE_NAME: your Spanner instance name.
    • DATABASE_NAME: your Spanner database name.
    • DIALECT_NAME: your Spanner SQL dialect. Acceptsgooglesql orpostgresql. Defaults togooglesql if undefined.
  4. Start the Gemini CLI in interactive mode:
        gemini
     The CLI automatically loads the Spanner extension for Gemini CLI and its tools, which you can use to interact with your database.

Gemini Code Assist

We strongly recommend configuring Gemini Code Assist to use theGemini CLI, asthis approach removes the need to manually configure anMCP server. However, the directions to manually configure an MCP server arestill available in the following section:


1. Install theGemini Code Assist extension in VS Code.
2.Enable agent mode and switch the agent model to Gemini.
3. In your project root directory, create a folder named.gemini and, within it, asettings.json file.
4. Add one of the following configurations based on your Spanner dialect in thesettings.json file.
5. Replace the following variables with your values:
  • PROJECT_ID: your Google Cloud project ID.
  • INSTANCE_NAME: your Spanner instance name.
  • DATABASE_NAME: your Spanner database name.
6. Save the file.

Spanner withGoogleSQL dialect:

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

Spanner withPostgreSQL dialect:

{  "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. InstallClaude Code.
2. Create.mcp.json file in your project root, if it doesn't exist.
3. Add one of the following configurations based on yourSpanner dialect, replace the environment variables withyour values, and save the file:

Spanner withGoogleSQL dialect:

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

Spanner withPostgreSQL dialect:

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


1. OpenClaude for Desktop and navigate toSettings.
2. In theDeveloper tab, clickEdit Config to open the configuration file.
3. Add one of the following configurations based on yourSpanner dialect, replace the environment variables withyour values, and save the file:

Spanner withGoogleSQL dialect:

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

Spanner withPostgreSQL dialect:

{  "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. Restart Claude for Desktop.
5. The new chat screen displays a hammer (MCP) icon with the new MCP server.

Cline


1. OpenCline extension in VS Code and clickMCP Servers icon.
2. Tap Configure MCP Servers to open the configuration file.
3. Add one of the following configurations based on yourSpanner dialect, replace the environment variables withyour values, and save the file:

Spanner withGoogleSQL dialect:

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

Spanner withPostgreSQL dialect:

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

A green active status appears after the server connects successfully.

Cursor


1. Create the.cursor directory in your project root if it doesn't exist.
2. Create the.cursor/mcp.json file if it doesn't exist and open it.
3. Add one of the following configurations based on yourSpanner dialect, replace the environment variables withyour values, and save the file:

Spanner withGoogleSQL dialect:

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

Spanner withPostgreSQL dialect:

{  "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. OpenCursor and navigate toSettings > Cursor Settings > MCP. A green active status appears when the server connects.

Visual Studio Code (Copilot)


1. OpenVS Code and create.vscode directory in your project root if it does not exist.
2. Create the.vscode/mcp.json file if it doesn't exist, and open it.
3. Add one of the following configurations based on yourSpanner dialect, replace the environment variables withyour values, and save the file:

Spanner withGoogleSQL dialect:

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

Spanner withPostgreSQL dialect:

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

Windsurf


1. OpenWindsurf and navigate to Cascade assistant.
2. Click the MCP icon, then clickConfigure to open the configuration file.
3. Add one of the following configurations based on yourSpanner dialect, replace the environment variables withyour values, and save the file:

Spanner withGoogleSQL dialect:

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

Spanner withPostgreSQL dialect:

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

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.