En este documento se describe cómo conectar tu instancia de Spanner a IDEs que admitan el Model Context Protocol (MCP). MCP es un protocolo abierto para conectar modelos de lenguaje extenso (LLMs) a fuentes de datos como Spanner. Una vez que se haya establecido la conexión, tus agentes LLM podrán consultar e interactuar con tu instancia de Spanner.
En este documento se describe el proceso de conexión de los siguientes IDEs:
- Gemini CLI
- Gemini Code Assist
- Claude Code
- Claude para ordenadores
- Cline (extensión de VS Code)
- Cursor
- Visual Studio Code (Copilot)
- Windsurf (Codium)
Antes de empezar
En la Google Cloud consola, en la página del selector de proyectos, selecciona o crea un Google Cloud proyecto.
Asegúrate de que la facturación esté habilitada en tu Google Cloud proyecto.
Configurar la instancia de Spanner
Crea o selecciona una instancia y una base de datos de Spanner.
Configura los roles y permisos necesarios para completar esta tarea. El usuario que invoca los agentes LLM necesita el rol Usuario de base de datos de Spanner (
roles/spanner.databaseUser) o permisos de gestión de identidades y accesos equivalentes para conectarse a la instancia. Este rol es obligatorio a nivel de base de datos.Configura las credenciales predeterminadas de la aplicación (ADC) en tu entorno.
Instalar la caja de herramientas de MCP
Descarga la versión más reciente de la caja de herramientas de MCP como archivo binario. Selecciona el binario correspondiente a tu sistema operativo y a la arquitectura de tu CPU. Debes usar la versión 0.7.0 o una posterior de MCP Toolbox:
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
Haz que el archivo binario sea ejecutable:
chmod +x toolboxVerifica la instalación:
./toolbox --version
Configurar el IDE de MCP
Gemini CLI
1. Instala la CLI de Gemini.
2. En el directorio raíz de tu proyecto, crea una carpeta llamada
.gemini y, dentro de ella, un archivo settings.json.3. Añade una de las siguientes configuraciones en función de tu dialecto de Spanner en el archivo
settings.json.4. Sustituye las siguientes variables por tus valores:
PROJECT_ID: tu ID de proyecto Google Cloud .INSTANCE_NAME: nombre de la instancia de Spanner.DATABASE_NAME: 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"
}
}
}
}
Gemini Code Assist
1. Instala la extensión Gemini Code Assist en VS Code.
2. Habilita el modo Agente y cambia el modelo del 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. Añade una de las siguientes configuraciones en función de tu dialecto de Spanner en el archivo
settings.json.5. Sustituye las siguientes variables por tus valores:
PROJECT_ID: tu ID de proyecto Google Cloud .INSTANCE_NAME: nombre de la instancia de Spanner.DATABASE_NAME: 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
1. Instala Claude Code.
2. Crea el archivo
.mcp.json en la raíz de tu proyecto, si no existe. 3. Añade una de las siguientes configuraciones en función de tu dialecto de Spanner, sustituye las variables de entorno por tus valores y guarda el archivo:
Spanner con el 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 para ordenadores
1. Abre Claude para ordenadores 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. Añade una de las siguientes configuraciones en función de tu dialecto de Spanner, sustituye las variables de entorno por tus valores y guarda el archivo:
Spanner con el 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. Reinicia Claude para ordenadores.
5. En la nueva pantalla de chat se muestra un icono de martillo (MCP) con el nuevo servidor MCP.
Cline
1. Abre la extensión Cline en VS Code y haz clic en el icono Servidores MCP.
2. Toca Configurar servidores MCP para abrir el archivo de configuración.
3. Añade una de las siguientes configuraciones en función de tu dialecto de Spanner, sustituye las variables de entorno por tus valores y guarda el archivo:
Spanner con el 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"
}
}
}
}
Si el servidor se conecta correctamente, aparecerá el estado activo en verde.
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. Añade una de las siguientes configuraciones en función de tu dialecto de Spanner, sustituye las variables de entorno por tus valores y guarda el archivo:
Spanner con el 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 ve a Configuración > Configuración del cursor > MCP. Cuando el servidor se conecta, aparece el estado activo en 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. Añade una de las siguientes configuraciones en función de tu dialecto de Spanner, sustituye las variables de entorno por tus valores y guarda el archivo:
Spanner con el 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 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 ve al asistente de Cascade.
2. Haz clic en el icono de MCP y, a continuación, en Configurar para abrir el archivo de configuración.
3. Añade una de las siguientes configuraciones en función de tu dialecto de Spanner, sustituye las variables de entorno por tus valores y guarda el archivo:
Spanner con el 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"
}
}
}
}
Interactuar con una instancia de Spanner
Tu IDE ahora está conectado a Spanner mediante MCP. Tu agente LLM ahora puede enumerar tablas, crear tablas o definir y ejecutar otras instrucciones SQL.
El LLM tiene acceso a las siguientes herramientas:
- list_tables muestra las tablas y las descripciones.
- execute_sql ejecuta cualquier instrucción SQL.
- execute_sql_dql ejecuta una instrucción SQL DQL.