Utilizzare Spanner con MCP Toolbox for Databases, l'interfaccia a riga di comando di Gemini e altri agenti

Questo documento descrive come connettere l'istanza Spanner a vari strumenti per sviluppatori che supportano il Model Context Protocol (MCP).

Ti consigliamo di utilizzare l'estensione Spanner dedicata per Gemini CLI. L'estensione raggruppa le competenze sottostanti direttamente nell'estensione, il che semplifica l'installazione e la configurazione. Puoi configurare Gemini Code Assist per utilizzare Gemini CLI, offrendo vantaggi di configurazione simili nel tuo IDE. Per maggiori informazioni, consulta Estensione Gemini CLI - Spanner.

In alternativa, altri IDE e strumenti per sviluppatori che supportano MCP possono connettersi tramite MCP Toolbox for Databases. MCP Toolbox è un server MCP open source progettato per connettere gli agenti AI ai tuoi dati. Gestisce attività come l'autenticazione e il pool di connessioni, consentendoti di interagire con i tuoi dati con il linguaggio naturale direttamente dal tuo IDE.

Utilizzare l'estensione Gemini CLI in Spanner

L'integrazione di Spanner con Gemini CLI avviene tramite un'estensione open source che offre funzionalità aggiuntive rispetto alla connessione MCP Toolbox standard. L'estensione offre una procedura di installazione semplificata e un insieme di competenze basate su MCP Tools. Se utilizzi l'estensione Gemini CLI, non devi installare MCP Toolbox. Per maggiori informazioni, consulta Estensione Gemini CLI - Spanner.

L'estensione spanner include competenze per elencare le tabelle ed eseguire istruzioni SQL e SQL DQL.

Per tutte le competenze disponibili, consulta le competenze Spanner su GitHub.

Prima di iniziare

  1. Nella Google Cloud console, nella pagina di selezione del progetto, seleziona o crea un Google Cloud progetto.

  2. Verifica che la fatturazione sia attivata per il tuo Google Cloud progetto.

Configurare l'istanza Spanner

  1. Abilita l'API Spanner nel Google Cloud progetto.

  2. Crea o seleziona un'istanza e un database Spanner.

  3. Configura i ruoli e le autorizzazioni richiesti per completare questa attività. L'utente che richiama gli agenti LLM ha bisogno dei seguenti ruoli a livello di database:

    • Cloud Spanner Database Reader (roles/spanner.databaseReader) per eseguire query DQL ed elencare le tabelle.

    • Utente database Cloud Spanner (roles/spanner.databaseUser) per eseguire query DML.

  4. Configura le Credenziali predefinite dell'applicazione (ADC) per il tuo ambiente.

Installare MCP Toolbox

  1. Scarica l'ultima versione di MCP Toolbox come file binario. Seleziona il file binario corrispondente al sistema operativo e all'architettura della CPU. Devi utilizzare MCP Toolbox versione 0.15.0 o successive:

    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. Rendi eseguibile il file binario:

    chmod +x toolbox

  3. Verifica l'installazione:

    ./toolbox --version

Configurare client e connessioni

Questa sezione descrive come configurare vari strumenti per sviluppatori per connetterti all'istanza Spanner. Seleziona il client tra le seguenti opzioni:

Gemini CLI

  1. Installa il Gemini CLI.
  2. Installa l'estensione Spanner per Gemini CLI da il repository GitHub utilizzando il seguente comando: 
    gemini extensions install https://github.com/gemini-cli-extensions/spanner
  3. Imposta le seguenti variabili di ambiente per connetterti all'istanza Spanner: 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Sostituisci quanto segue:
    • PROJECT_ID: l' Google Cloud ID progetto.
    • INSTANCE_NAME: il nome dell'istanza Spanner.
    • DATABASE_NAME: il nome del database Spanner.
    • DIALECT_NAME: il dialetto SQL di Spanner. Accetta googlesql o postgresql. Se non è definito, il valore predefinito è googlesql.
  4. Avvia Gemini CLI in modalità interattiva: 
    gemini

    L'interfaccia a riga di comando carica automaticamente l'estensione Spanner per Gemini CLI e le relative competenze, che puoi utilizzare per interagire con il database.

    In Gemini CLI, utilizza il /extensions comando per verificare che l'estensione sia installata.

Gemini Code Assist

Ti consigliamo vivamente di configurare Gemini Code Assist per utilizzare il Gemini CLI, in quanto questo approccio elimina la necessità di configurare manualmente un server MCP. Tuttavia, le istruzioni per configurare manualmente un server MCP sono ancora disponibili nella sezione seguente:


1. Installa l'estensione Gemini Code Assist in VS Code.
2. Attiva la modalità agente e imposta il modello dell'agente su Gemini.
3. Nella directory principale del progetto, crea una cartella denominata .gemini e, al suo interno, un file settings.json.
4. Aggiungi una delle seguenti configurazioni in base al dialetto Spanner nel file settings.json.
5. Sostituisci le seguenti variabili con i tuoi valori:
  • PROJECT_ID: l'ID del tuo Google Cloud progetto.
  • INSTANCE_NAME: il nome dell'istanza Spanner.
  • DATABASE_NAME: il nome del database Spanner.
6. Salva il file.

Spanner con dialetto 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 dialetto 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. Installa Claude Code.
  2. Imposta le variabili di ambiente per connetterti all'istanza Spanner: 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Sostituisci quanto segue:
    • PROJECT_ID: l' Google Cloud ID progetto.
    • INSTANCE_NAME: il nome dell'istanza Spanner.
    • DATABASE_NAME: il nome del database Spanner.
    • DIALECT_NAME: il dialetto SQL di Spanner. Accetta googlesql o postgresql. Se non è definito, il valore predefinito è googlesql.
  3. Avvia l'agente: 
    claude
  4. Installa il plug-in: 
    /plugin install spanner@claude-plugins-official

Codex

  1. Installa il marketplace Data Agent Kit: 
    codex plugin marketplace add GoogleCloudPlatform/data-agent-kit
  2. Installa il plug-in Spanner: 
    codex plugin install spanner@data-agent-kit
  3. Configura le variabili di ambiente per connetterti all'istanza Spanner: 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Sostituisci quanto segue:
    • PROJECT_ID: l' Google Cloud ID progetto.
    • INSTANCE_NAME: il nome dell'istanza Spanner.
    • DATABASE_NAME: il nome del database Spanner.
    • DIALECT_NAME: il dialetto SQL di Spanner. Accetta googlesql o postgresql. Se non è definito, il valore predefinito è googlesql.
  4. (Facoltativo) Aggiorna il marketplace: 
    codex plugin marketplace upgrade data-agent-kit

Claude per desktop


1. Apri Claude per desktop e vai a Impostazioni.
2. Nella scheda Sviluppatore, fai clic su Modifica configurazione per aprire il file di configurazione.
3. Aggiungi una delle seguenti configurazioni in base al tuo dialetto Spanner, sostituisci le variabili di ambiente con i tuoi valori e salva il file:

Spanner con dialetto 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 dialetto 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. Riavvia Claude per desktop.
5. Nella nuova schermata di chat viene visualizzata un'icona a forma di martello (MCP) con il nuovo server MCP.

Cline


1. Apri l'estensione Cline in VS Code e fai clic sull'icona Server MCP.
2. Tocca Configura server MCP per aprire il file di configurazione.
3. Aggiungi una delle seguenti configurazioni in base al tuo dialetto Spanner, sostituisci le variabili di ambiente con i tuoi valori e salva il file:

Spanner con dialetto 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 dialetto 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"
      }
    }
  }
}

Dopo la connessione al server, viene visualizzato uno stato attivo verde.

Cursore


1. Crea la directory .cursor nella directory principale del progetto, se non esiste.
2. Crea il file .cursor/mcp.json se non esiste e aprilo.
3. Aggiungi una delle seguenti configurazioni in base al tuo dialetto Spanner, sostituisci le variabili di ambiente con i tuoi valori e salva il file:

Spanner con dialetto 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 dialetto 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. Apri Cursore e vai a Impostazioni > Impostazioni cursore > MCP. Quando il server si connette, viene visualizzato uno stato attivo verde.

Visual Studio Code (Copilot)


1. Apri VS Code e crea la directory .vscode nella directory principale del progetto, se non esiste.
2. Crea il file .vscode/mcp.json se non esiste e aprilo.
3. Aggiungi una delle seguenti configurazioni in base al tuo dialetto Spanner, sostituisci le variabili di ambiente con i tuoi valori e salva il file:

Spanner con dialetto 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 dialetto 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. Apri Windsurf e vai all'assistente Cascade.
2. Fai clic sull'icona MCP, quindi su Configura per aprire il file di configurazione.
3. Aggiungi una delle seguenti configurazioni in base al tuo dialetto Spanner, sostituisci le variabili di ambiente con i tuoi valori e salva il file:

Spanner con dialetto 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 dialetto 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"
      }
    }
  }
}

Connettersi ad Antigravity

Puoi connettere Spanner ad Antigravity nei seguenti modi:

  • Utilizzando l'MCP Store
  • Utilizzando una configurazione personalizzata

MCP Store

Il modo più consigliato per connetterti a Antigravity è utilizzare l'MCP Store integrato.

  1. Apri Antigravity e il riquadro dell'agente dell'editor.
  2. Fai clic sull'icona Menu nella parte superiore del riquadro e seleziona Server MCP.
  3. Individua Spanner nell'elenco dei server disponibili e fai clic su Installa.
  4. Segui i passaggi sullo schermo per autorizzare Antigravity ad accedere al tuo progetto Google Cloud. In questo modo, Antigravity può accedere all'istanza Spanner nel tuo progetto.

Una volta installato il server Spanner nell'MCP Store, le risorse e le competenze del server sono disponibili per l'editor.

Configurazione personalizzata

Per connetterti a un server MCP personalizzato, segui questi passaggi:

  1. Apri Antigravity e il riquadro dell'agente dell'editor.
  2. Fai clic sull'icona Menu nella parte superiore del riquadro e seleziona Server MCP.
  3. Fai clic su Gestisci server MCP > Visualizza configurazione non elaborata per aprire il file mcp_config.json.
  4. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva.
{
  "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"
      }
    }
  }
}

Dopo aver configurato il server MCP personalizzato, le risorse e le competenze del server Spanner sono disponibili per l'editor.

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del tuo Google Cloud progetto.
  • INSTANCE_NAME: il nome dell'istanza Spanner.
  • DATABASE_NAME: il nome del database Spanner.
  • DIALECT_NAME: il dialetto SQL di Spanner. Accetta googlesql o postgresql. Se non specifichi un dialetto, il valore predefinito è googlesql.

Connettersi a Spanner in VS Code utilizzando l'estensione Data Agent Kit

L'estensione Google Cloud Data Agent Kit ti consente di gestire il database Spanner ed eseguire query sui dati Spanner nel tuo IDE preferito. Sono supportati Visual Studio Code e tutti gli IDE basati su VS Code.

Questa estensione fornisce funzionalità di rilevamento ed esplorazione dei dati, consentendoti di porre domande sui dati Spanner in linguaggio naturale. Aiuta a eliminare il cambio di contesto tra gli strumenti a riga di comando di Spanner e l'ambiente di sviluppo. Data Agent Kit also fornisce plug-in CLI da utilizzare con le tue Google Cloud risorse.

Per maggiori informazioni, consulta la panoramica dell'estensione Data Agent Kit per VS Code.