Connect your IDE to Spanner

This document describes how to connect your Spanner instance to IDEs that support the Model Context Protocol (MCP). MCP is an open protocol for connecting large language models (LLMs) to data sources like Spanner. After connection, your LLM agents can query and interact with your Spanner instance.

This document describes the connection process for the following IDEs:

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 Spanner Database User role (roles/spanner.databaseUser) or equivalent Identity and Access Management permissions to connect to the instance. This role is required at the database level.

  4. Configure Application Default Credentials (ADC) for your environment.

Install the MCP Toolbox

  1. Download the latest version of the MCP Toolbox as a binary. Select the binary corresponding to your operating system (OS) and CPU architecture. You must use MCP Toolbox version 0.6.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 MCP IDE

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: 

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

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

Interact with your Spanner instance

Your IDE is now connected to Spanner using MCP. Your LLM agent can now list tables, create tables, or define and execute other SQL statements.

The following tools are available to the LLM:

  • list_tables: lists tables and descriptions
  • execute_sql: execute any SQL statement
  • execute_sql_dql: execute DQL SQL statement