This document describes how to connect your Spanner instance to
various developer tools that support the
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction).

We recommend using the dedicated Spanner
extension for [Gemini CLI](https://docs.cloud.google.com/gemini/docs/codeassist/gemini-cli.md.txt).
The extension bundles the underlying skills directly into the extension, which
simplifies setup and configuration. 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](https://github.com/gemini-cli-extensions/spanner).

Alternatively, other IDEs and developer tools supporting the MCP can connect
through
[MCP Toolbox for Databases](https://github.com/googleapis/mcp-toolbox).
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

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 a streamlined
installation process and a set of skills based on MCP Tools. If you use the
Gemini CLI extension, you don't need to install MCP Toolbox. For more
information, see
[Gemini CLI Extension - Spanner](https://github.com/gemini-cli-extensions/spanner).

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

For all available skills, see the [Spanner skills on GitHub](https://github.com/gemini-cli-extensions/spanner/tree/main/skills).

## Before you begin

1. In the Google Cloud console, on the
   [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard),
   select or create a Google Cloud project.

2. [Make sure that billing is enabled for your Google Cloud project](https://docs.cloud.google.com/billing/docs/how-to/verify-billing-enabled.md.txt#confirm_billing_is_enabled_on_a_project).

## Set up the Spanner instance

1. [Enable the Spanner API in the Google Cloud project](https://console.cloud.google.com/apis/enableflow?apiid=spanner.googleapis.com&redirect=https://console.cloud.google.com/).

2. [Create or select a Spanner instance and database](https://docs.cloud.google.com/spanner/docs/create-query-database-console.md.txt).

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)](https://docs.cloud.google.com/docs/authentication/set-up-adc-local-dev-environment.md.txt) for your environment.

## Install MCP Toolbox

> [!NOTE]
> **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](https://github.com/googleapis/mcp-toolbox/releases/latest) 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/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. Make the binary executable:

   ```bash
   chmod +x toolbox
   ```
3. Verify the installation:

   ```bash
   ./toolbox --version
   ```

## Set up clients and connections

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

### Gemini CLI

1. Install the [Gemini CLI.](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#-installation)
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:
   - <var translate="no">PROJECT_ID</var>: The Google Cloud project ID.
   - <var translate="no">INSTANCE_NAME</var>: The Spanner instance name.
   - <var translate="no">DATABASE_NAME</var>: The Spanner database name.
   - <var translate="no">DIALECT_NAME</var>: The 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 skills, which you can use to interact with your database.

   In the Gemini CLI, use the [`/extensions`](https://github.com/google-gemini/gemini-cli/blob/bbcc90613390e4d3d3aed911fbc1535af80d643b/docs/cli/commands.md)
   command to verify the extension is installed.

### Gemini Code Assist

We strongly recommend configuring Gemini Code Assist to use the
[Gemini CLI](https://docs.cloud.google.com/spanner/docs/pre-built-tools-with-mcp-toolbox.md.txt#mcp-configure-your-mcp-client-geminicli), 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](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in VS Code.  
2. [Enable agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-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](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview).
2. Set the environment variables to connect to your Spanner instance:

   ```sh
   export SPANNER_PROJECT="PROJECT_ID"
   export SPANNER_INSTANCE="INSTANCE_NAME"
   export SPANNER_DATABASE="DATABASE_NAME"
   export SPANNER_DIALECT="DIALECT_NAME"
   ```
   Replace the following:
   - <var translate="no">PROJECT_ID</var>: The Google Cloud project ID.
   - <var translate="no">INSTANCE_NAME</var>: The Spanner instance name.
   - <var translate="no">DATABASE_NAME</var>: The Spanner database name.
   - <var translate="no">DIALECT_NAME</var>: The Spanner SQL dialect. Accepts `googlesql` or `postgresql`. Defaults to `googlesql` if undefined.
3. Start the agent:

   ```sh
   claude
   ```
4. Install the plugin:

   ```sh
   /plugin install spanner@claude-plugins-official
   ```

> [!TIP]
> **Tip:** Run `/plugin list` inside Claude Code to verify the plugin is active, or `/reload-plugins` if you just installed it.

### Codex

1. Install the Data Cloud Plugins marketplace:

   ```sh
   codex plugin marketplace add GoogleCloudPlatform/data-cloud-plugins
   ```
2. Install the Spanner plugin:

   ```sh
   codex plugin install spanner@data-cloud-plugins
   ```
3. Configure the environment variables to connect to your Spanner instance:

   ```sh
   export SPANNER_PROJECT="PROJECT_ID"
   export SPANNER_INSTANCE="INSTANCE_NAME"
   export SPANNER_DATABASE="DATABASE_NAME"
   export SPANNER_DIALECT="DIALECT_NAME"
   ```
   Replace the following:
   - <var translate="no">PROJECT_ID</var>: The Google Cloud project ID.
   - <var translate="no">INSTANCE_NAME</var>: The Spanner instance name.
   - <var translate="no">DATABASE_NAME</var>: The Spanner database name.
   - <var translate="no">DIALECT_NAME</var>: The Spanner SQL dialect. Accepts `googlesql` or `postgresql`. Defaults to `googlesql` if undefined.
4. Optional. Update the marketplace:

   ```sh
   codex plugin marketplace upgrade data-cloud-plugins
   ```

### Claude for Desktop

<br />

1. Open [Claude for Desktop](https://claude.ai/download) 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

<br />

1. Open [Cline](https://github.com/cline/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

<br />

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](https://www.cursor.com/) and navigate to **Settings \> Cursor Settings \> MCP** . A green active status appears when the server connects.   

### Visual Studio Code (Copilot)

<br />

1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) 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

<br />

1. Open [Windsurf](https://docs.codeium.com/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](https://antigravity.google/docs/mcp) is by using the built-in MCP Store.

1. Open [Antigravity](https://antigravity.google/docs/mcp) 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 skills from the server are available to the editor.

### Custom configuration

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

1. Open [Antigravity](https://antigravity.google/docs/mcp) 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 skills 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`.

## Connect to Spanner using Data Agent Kit

Google Cloud Data Agent Kit lets you manage your Spanner database and
execute queries against your Spanner data in your preferred IDE
or coding agent. The Data Agent Kit extension works with
Visual Studio Code and VS Code-based IDEs, and the Data Agent Kit
plugin works with a number of popular coding agents, including Claude Code and
Codex CLI.

Data Agent Kit provides data discovery and exploration
capabilities, letting you ask questions about your Spanner data
in natural language. It helps eliminate context switching between
Spanner command-line tools and your development environment.

For more information, see [Data Agent Kit
overview](https://docs.cloud.google.com/data-agent-kit/overview).