Usa Spanner con el kit de herramientas de MCP para bases de datos, Gemini CLI y otros agentes

En este documento, se describe cómo conectar tu instancia de Spanner a varias herramientas para desarrolladores que admiten el Protocolo de contexto del modelo (MCP).

Te recomendamos que uses la extensión de Spanner dedicada para Gemini CLI. La extensión agrupa las habilidades subyacentes directamente en la extensión, lo que simplifica la configuración. Puedes configurar Gemini Code Assist para que use la CLI de Gemini, lo que ofrece beneficios de configuración similares en tu IDE. Para obtener más información, consulta Extensión de Gemini CLI: Spanner.

Como alternativa, otros IDEs y herramientas para desarrolladores que admiten el MCP pueden conectarse a través de MCP Toolbox para bases de datos. MCP Toolbox es un servidor de MCP de código abierto diseñado para conectar agentes de IA a tus datos. Maneja tareas como la autenticación y la agrupación de conexiones, lo que te permite interactuar con tus datos en lenguaje natural directamente desde tu IDE.

Usa la extensión de Gemini CLI en Spanner

La integración de Spanner con Gemini CLI se realiza a través de una extensión de código abierto que ofrece capacidades adicionales en comparación con la conexión estándar de MCP Toolbox. La extensión ofrece un proceso de instalación optimizado y un conjunto de habilidades basadas en las herramientas de MCP. Si usas la extensión de Gemini CLI, no necesitas instalar MCP Toolbox. Para obtener más información, consulta Extensión de Gemini CLI: Spanner.

La extensión spanner incluye habilidades para enumerar tablas y ejecutar instrucciones de SQL y DQL de SQL.

Para ver todas las habilidades disponibles, consulta las habilidades de Spanner en GitHub.

Antes de comenzar

  1. En la consola de Google Cloud , en la página del selector de proyectos, selecciona o crea un proyecto de Google Cloud .

  2. Asegúrate de tener habilitada la facturación para tu proyecto de Google Cloud .

Configura la instancia de Spanner

  1. Habilita la API de Spanner en el Google Cloud proyecto.

  2. Crea o selecciona una instancia y una base de datos de Spanner.

  3. Configura los roles y permisos necesarios para completar esta tarea. El usuario que invoca a los agentes de LLM necesita los siguientes roles a nivel de la base de datos:

    • Lector de base de datos de Cloud Spanner (roles/spanner.databaseReader) para ejecutar consultas de DQL y enumerar tablas

    • Usuario de base de datos de Cloud Spanner (roles/spanner.databaseUser) para ejecutar consultas de DML

  4. Configura las credenciales predeterminadas de la aplicación (ADC) para tu entorno.

Instala MCP Toolbox

  1. Descarga la versión más reciente de MCP Toolbox como un objeto binario. Selecciona el objeto binario correspondiente a tu sistema operativo (SO) y a la arquitectura de la CPU. Debes usar la versión 0.15.0 o una posterior de MCP Toolbox:

    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. Haz que el objeto binario sea ejecutable:

    chmod +x toolbox

  3. Verifica la instalación:

    ./toolbox --version

Configura clientes y conexiones

En esta sección, se describe cómo configurar varias herramientas para desarrolladores para conectarse a tu instancia de Spanner. Selecciona tu cliente entre las siguientes opciones:

Gemini CLI

  1. Instala la Gemini CLI.
  2. Instala la extensión de Spanner para Gemini CLI desde el repositorio de GitHub con el siguiente comando: 
    gemini extensions install https://github.com/gemini-cli-extensions/spanner
  3. Configura las siguientes variables de entorno para conectarte a tu instancia de Spanner: 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Reemplaza lo siguiente:
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • INSTANCE_NAME: Es el nombre de la instancia de Spanner.
    • DATABASE_NAME: Es el nombre de la base de datos de Spanner.
    • DIALECT_NAME: Es el dialecto de SQL de Spanner. Se acepta googlesql o postgresql. El valor predeterminado es googlesql si no se define.
  4. Inicia Gemini CLI en modo interactivo: 
    gemini

    La CLI carga automáticamente la extensión de Spanner para Gemini CLI y sus habilidades, que puedes usar para interactuar con tu base de datos.

    En Gemini CLI, usa el comando /extensions para verificar que la extensión esté instalada.

Gemini Code Assist

Te recomendamos que configures Gemini Code Assist para que use la CLI de Gemini, ya que este enfoque elimina la necesidad de configurar manualmente un servidor de MCP. Sin embargo, las instrucciones para configurar manualmente un servidor de MCP aún están disponibles en la siguiente sección:


 1. Instala la extensión Gemini Code Assist en VS Code.
2. Habilita el modo agente y cambia el modelo de agente a Gemini.
3. En el directorio raíz de tu proyecto, crea una carpeta llamada .gemini y, dentro de ella, un archivo settings.json.
4. Agrega una de las siguientes configuraciones según tu dialecto de Spanner en el archivo settings.json.
5. Reemplaza las siguientes variables por tus valores:
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • INSTANCE_NAME: Es el nombre de tu instancia de Spanner.
  • DATABASE_NAME: Es el nombre de tu base de datos de Spanner.
6. Guarda el archivo.

Spanner con dialecto GoogleSQL: 

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

Spanner con el dialecto de PostgreSQL: 

{
  "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. Instala Claude Code.
  2. Establece las variables de entorno para conectarte a tu instancia de Spanner: 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Reemplaza lo siguiente:
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • INSTANCE_NAME: Es el nombre de la instancia de Spanner.
    • DATABASE_NAME: Es el nombre de la base de datos de Spanner.
    • DIALECT_NAME: Es el dialecto de SQL de Spanner. Se acepta googlesql o postgresql. El valor predeterminado es googlesql si no se define.
  3. Inicia el agente: 
    claude
  4. Instala el complemento: 
    /plugin install spanner@claude-plugins-official

Codex

  1. Instala el mercado de complementos de Data Cloud: 
    codex plugin marketplace add GoogleCloudPlatform/data-cloud-plugins
  2. Instala el complemento de Spanner: 
    codex plugin install spanner@data-cloud-plugins
  3. Configura las variables de entorno para conectarte a tu instancia de Spanner: 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Reemplaza lo siguiente:
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • INSTANCE_NAME: Es el nombre de la instancia de Spanner.
    • DATABASE_NAME: Es el nombre de la base de datos de Spanner.
    • DIALECT_NAME: Es el dialecto de SQL de Spanner. Se acepta googlesql o postgresql. El valor predeterminado es googlesql si no se define.
  4. Es opcional. Actualiza el mercado: 
    codex plugin marketplace upgrade data-cloud-plugins

Claude para computadoras


 1. Abre Claude para computadoras y ve a Configuración.
2. En la pestaña Desarrollador, haz clic en Editar configuración para abrir el archivo de configuración.
3. Agrega una de las siguientes configuraciones según tu dialecto de Spanner, reemplaza las variables de entorno por tus valores y guarda el archivo:

Spanner con dialecto GoogleSQL: 

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

Spanner con el dialecto de PostgreSQL: 

{
  "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. Reinicia Claude para computadoras.
5. En la nueva pantalla de chat, se muestra un ícono de martillo (MCP) con el nuevo servidor de MCP.

Cline


 1. Abre la extensión Cline en VS Code y haz clic en el ícono MCP Servers.
2. Presiona Configure MCP Servers para abrir el archivo de configuración.
3. Agrega una de las siguientes configuraciones según tu dialecto de Spanner, reemplaza las variables de entorno por tus valores y guarda el archivo:

Spanner con dialecto GoogleSQL: 

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

Spanner con el dialecto de PostgreSQL: 

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

Aparece un estado activo de color verde después de que el servidor se conecta correctamente.

Cursor


 1. Crea el directorio .cursor en la raíz del proyecto si no existe.
2. Crea el archivo .cursor/mcp.json si no existe y ábrelo.
3. Agrega una de las siguientes configuraciones según tu dialecto de Spanner, reemplaza las variables de entorno por tus valores y guarda el archivo:

Spanner con dialecto de GoogleSQL: 

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

Spanner con el dialecto de PostgreSQL: 

{
  "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. Abre Cursor y navega a Configuración > Configuración del cursor > MCP. Cuando el servidor se conecta, aparece un estado activo de color verde.

Visual Studio Code (Copilot)


 1. Abre VS Code y crea el directorio .vscode en la raíz de tu proyecto si no existe.
2. Crea el archivo .vscode/mcp.json si no existe y ábrelo.
3. Agrega una de las siguientes configuraciones según tu dialecto de Spanner, reemplaza las variables de entorno por tus valores y guarda el archivo:

Spanner con dialecto GoogleSQL: 

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

Spanner con el dialecto de PostgreSQL: 

{
  "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. Abre Windsurf y navega al asistente de Cascade.
2. Haz clic en el ícono de MCP y, luego, en Configurar para abrir el archivo de configuración.
3. Agrega una de las siguientes configuraciones según tu dialecto de Spanner, reemplaza las variables de entorno por tus valores y guarda el archivo:

Spanner con dialecto GoogleSQL: 

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

Spanner con el dialecto de PostgreSQL: 

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

Conéctate con Antigravity

Puedes conectar Spanner a Antigravity de las siguientes maneras:

  • Cómo usar MCP Store
  • Cómo usar una configuración personalizada

Tienda de MCP

La forma más recomendada de conectarse a Antigravity es a través de la MCP Store integrada.

  1. Abre Antigravity y el panel del agente del editor.
  2. Haz clic en el ícono de menú en la parte superior del panel y selecciona Servidores de MCP.
  3. Ubica Spanner en la lista de servidores disponibles y haz clic en Instalar.
  4. Sigue los pasos que aparecen en pantalla para autorizar a Antigravity a acceder a tu proyecto de Google Cloud. Esto permite que Antigravity acceda a la instancia de Spanner en tu proyecto.

Una vez que instales el servidor de Spanner en MCP Store, los recursos y las habilidades del servidor estarán disponibles para el editor.

Configuración personalizada

Para conectarte a un servidor de MCP personalizado, sigue estos pasos:

  1. Abre Antigravity y el panel del agente del editor.
  2. Haz clic en el ícono de menú en la parte superior del panel y selecciona Servidores de MCP.
  3. Haz clic en Manage MCP Servers > View raw config para abrir el archivo mcp_config.json.
  4. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda los cambios.
{
  "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"
      }
    }
  }
}

Una vez que configures el servidor de MCP personalizado, los recursos y las habilidades del servidor de Spanner estarán disponibles para el editor.

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • INSTANCE_NAME: Es el nombre de tu instancia de Spanner.
  • DATABASE_NAME: Es el nombre de tu base de datos de Spanner.
  • DIALECT_NAME: Es tu dialecto de Spanner SQL. Se acepta googlesql o postgresql. Si no especificas un dialecto, el valor predeterminado es googlesql.

Conéctate a Spanner con el Data Agent Kit

Google Cloud Data Agent Kit te permite administrar tu base de datos de Spanner y ejecutar consultas en tus datos de Spanner en tu IDE o agente de programación preferido. La extensión Data Agent Kit funciona con Visual Studio Code y los IDE basados en VS Code, y el complemento Data Agent Kit funciona con varios agentes de programación populares, incluidos Claude Code y Codex CLI.

Data Agent Kit proporciona capacidades de descubrimiento y exploración de datos, lo que te permite hacer preguntas sobre tus datos de Spanner en lenguaje natural. Ayuda a eliminar el cambio de contexto entre las herramientas de línea de comandos de Spanner y tu entorno de desarrollo.

Para obtener más información, consulta la descripción general del Kit de Data Agent.