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 Gemini CLI, 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 IDE 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 el agrupamiento de conexiones, lo que te permite interactuar con tus datos con 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 SQL DQL.
Para ver todas las habilidades disponibles, consulta las habilidades de Spanner en GitHub.
Antes de comenzar
En la Google Cloud consola, en la página del selector de proyectos, selecciona o crea un Google Cloud proyecto.
Asegúrate de tener habilitada la facturación para tu Google Cloud proyecto.
Configura la instancia de Spanner
Crea o selecciona una instancia y una base de datos de Spanner.
Configura los roles y los permisos requeridos 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 tablasUsuario de base de datos de Cloud Spanner (
roles/spanner.databaseUser) para ejecutar consultas de DML
Configura las credenciales predeterminadas de la aplicación (ADC) para tu entorno.
Instala MCP Toolbox
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 arquitectura de la CPU. Debes usar la versión 0.15.0 de MCP Toolbox o una posterior:
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
Haz que el objeto binario sea ejecutable:
chmod +x toolboxVerifica 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
- Instala el Gemini CLI.
- 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
- 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"
- PROJECT_ID: Es el ID del proyecto. 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. Acepta
googlesqlopostgresql. El valor predeterminado esgooglesqlsi no se define.
- 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
/extensionscomando para verificar que la extensión esté instalada.
Gemini Code Assist
Te recomendamos que configures Gemini Code Assist para que use el Gemini CLI, 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 de 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 de tu Google Cloud proyecto.INSTANCE_NAME: Es el nombre de la instancia de Spanner.DATABASE_NAME: Es el nombre de la base de datos de Spanner.
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 dialecto 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
- Instala Claude Code.
- 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"
- PROJECT_ID: Es el ID del proyecto. 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. Acepta
googlesqlopostgresql. El valor predeterminado esgooglesqlsi no se define.
- Inicia el agente:
claude
- Instala el complemento:
/plugin install spanner@claude-plugins-official
Codex
- Instala el marketplace de Data Agent Kit:
codex plugin marketplace add GoogleCloudPlatform/data-agent-kit
- Instala el complemento de Spanner:
codex plugin install spanner@data-agent-kit
- 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"
- PROJECT_ID: Es el ID del proyecto. 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. Acepta
googlesqlopostgresql. El valor predeterminado esgooglesqlsi no se define.
- Es opcional. Actualiza el marketplace:
codex plugin marketplace upgrade data-agent-kit
Claude para computadoras
1. Abre Claude para computadoras y navega 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 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 dialecto 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 de Cline en VS Code y haz clic en el ícono de servidores de MCP.
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 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 dialecto 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"
}
}
}
}
Aparecerá un estado activo verde después de que el servidor se conecte correctamente.
Cursor
1. Crea el directorio
.cursor en la raíz de tu 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 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 dialecto 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. Aparecerá un estado activo verde cuando el servidor se conecte.
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 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 dialecto 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 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 dialecto 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:
- Usa la tienda de MCP.
- Usa una configuración personalizada.
Tienda de MCP
La forma más recomendada de conectarse a Antigravity es usar la tienda de MCP integrada.
- Abre Antigravity y el panel de agentes del editor.
- Haz clic en el ícono de menú en la parte superior del panel y selecciona Servidores de MCP.
- Busca Spanner en la lista de servidores disponibles y haz clic en Instalar.
- 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 la tienda de MCP, 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:
- Abre Antigravity y el panel de agentes del editor.
- Haz clic en el ícono de menú en la parte superior del panel y selecciona Servidores de MCP.
- Haz clic en Administrar servidores de MCP > Ver configuración sin procesar para abrir el archivo
mcp_config.json. - 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 de tu Google Cloud proyecto.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. Aceptagooglesqlopostgresql. Si no especificas un dialecto, el valor predeterminado esgooglesql.
Conéctate a Spanner en VS Code con la extensión de Data Agent Kit
La extensión de Google Cloud Data Agent Kit te permite administrar tu base de datos de Spanner y ejecutar consultas en tus datos de Spanner en el IDE que prefieras. Se admiten Visual Studio Code y todos los IDE basados en VS Code.
Esta extensión proporciona capacidades de exploración y descubrimiento 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. Data Agent Kit also proporciona complementos de CLI para usar con tus Google Cloud recursos.
Para obtener más información, consulta extensión de Data Agent Kit para VS Code overview.