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

This document describes how to connect your Spanner instance to various developer tools that support the Model Context Protocol (MCP).

We recommend using the dedicated Spanner extension for Gemini 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, see Gemini CLI Extension - Spanner.

Alternatively, other IDEs and developer tools supporting the MCP can connect through MCP Toolbox for Databases. MCP Toolbox is an open-source MCP server designed to connect AI agents to your data. It handles tasks like authentication and connection pooling, letting you 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 see breaking changes until the first stable release. (v1.0)

The Spanner integration with Gemini CLI is through an open-source extension that offers additional capabilities compared to the standard MCP Toolbox connection. The extension offers an installation process and a set of tools, in addition to providing detailed information on installation, configuration, and usage examples. If you use the Gemini CLI extension, you don't need to install MCP Toolbox. For more information, see Gemini CLI Extension - Spanner.

The spanner extension includes tools for listing tables, and executing SQL and SQL DQL statements.

Tools	Example natural language prompt
list_tables	What tables do I have in my Spanner instance?
execute_sql	Insert test data into the products table.
execute_sql_dql	What products in the electronics category are sold in America?

Before you begin

1. In the Google Cloud console, on the project 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 user invoking 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. Configure Application Default Credentials (ADC) for your environment.

Install MCP Toolbox

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

1. Download the latest version of MCP Toolbox as a binary. Select the binary 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 +x toolbox
   

3. Verify the installation:

   ./toolbox --version
   

Set up the agent tool

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

Gemini CLI

1. Install the Gemini CLI.
   
2. Install the Spanner extension for Gemini CLI from the GitHub repository using the following command:
   

  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. Accepts googlesql or postgresql. Defaults to googlesql 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 the Gemini CLI, as this approach removes the need to manually configure an MCP server. However, the directions to manually configure an MCP server are still available in the following section:

1. Install the Gemini 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, a settings.json file.
4. Add one of the following configurations based on your Spanner dialect in the settings.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 with GoogleSQL 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 with PostgreSQL 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. Install Claude Code.
2. Create .mcp.json file in your project root, if it doesn't exist.
3. Add one of the following configurations based on your Spanner dialect, replace the environment variables with your values, and save the file:

Spanner with GoogleSQL 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 with PostgreSQL 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. Open Claude for Desktop and navigate to Settings.
2. In the Developer tab, click Edit Config to open the configuration file.
3. Add one of the following configurations based on your Spanner dialect, replace the environment variables with your values, and save the file:

Spanner with GoogleSQL 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 with PostgreSQL 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. Open Cline extension in VS Code and click MCP Servers icon.
2. Tap Configure MCP Servers to open the configuration file.
3. Add one of the following configurations based on your Spanner dialect, replace the environment variables with your values, and save the file:

Spanner with GoogleSQL 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 with PostgreSQL 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 your Spanner dialect, replace the environment variables with your values, and save the file:

Spanner with GoogleSQL 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 with PostgreSQL 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. Open Cursor and navigate to Settings > Cursor Settings > MCP. A green active status appears when the server connects.

Visual Studio Code (Copilot)

1. Open VS 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 your Spanner dialect, replace the environment variables with your values, and save the file:

Spanner with GoogleSQL 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 with PostgreSQL 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. Open Windsurf and navigate to Cascade assistant.
2. Click the MCP icon, then click Configure to open the configuration file.
3. Add one of the following configurations based on your Spanner dialect, replace the environment variables with your values, and save the file:

Spanner with GoogleSQL 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 with PostgreSQL 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"
      }
    }
  }
}

Connect with Antigravity

You can connect Spanner to Antigravity in the following ways:

• Using the MCP Store
• Using a custom configuration

MCP Store

The most recommended way to connect to Antigravity is by using the built-in MCP Store.

1. Open Antigravity and open the editor's agent panel.
2. Click the Menu icon at the top of the panel and select MCP Servers.
3. Locate Spanner in the list of available servers and click Install.
4. Follow the on-screen steps to authorize Antigravity to access your Google Cloud Project. This lets Antigravity access the Spanner instance on your project.

Once you install the Spanner server in the MCP Store, the resources and tools from the server are available to the editor.

Custom configuration

To connect to a custom MCP server, do the following steps:

1. Open Antigravity and open the editor's agent panel.
2. Click the Menu icon at the top of the panel and select MCP Servers.
3. Click Manage MCP Servers > View raw config to open the mcp_config.json file.
4. Add the following configuration, replace the environment variables with your values, and save.

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

Once you configure the custom MCP server, the resources and tools from the Spanner server are available to the editor.

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. Accepts googlesql or postgresql. If you don't specify a dialect, the default is googlesql.