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 al suo interno, il che semplifica la configurazione. Puoi configurare Gemini Code Assist per utilizzare Gemini CLI, offrendo vantaggi di configurazione simili nel tuo IDE. Per saperne di più, 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 raggruppamento delle 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 un processo di installazione semplificato e un insieme di competenze basate sugli strumenti MCP. Se utilizzi l'estensione Gemini CLI, non è necessario installare MCP Toolbox. Per saperne di più, consulta Estensione Gemini CLI - Spanner.

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

Per tutte le skill disponibili, consulta la pagina Spanner skills su GitHub.

Prima di iniziare

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

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

Configura l'istanza Spanner

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

  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 deve disporre 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.

Installa MCP Toolbox

  1. Scarica l'ultima versione di MCP Toolbox come file binario. Seleziona il file binario corrispondente al tuo 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 connettersi all'istanza Spanner. Seleziona il cliente da una delle seguenti opzioni:

Gemini CLI

  1. Installa Gemini CLI.
  2. Installa l'estensione Spanner per Gemini CLI dal repository GitHub utilizzando questo 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

    La CLI carica automaticamente l'estensione Spanner per Gemini CLI e le relative skill, che puoi utilizzare per interagire con il tuo database.

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

Gemini Code Assist

Ti consigliamo vivamente di configurare Gemini Code Assist in modo che utilizzi 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 passa al modello di agente Gemini.
3. Nella directory radice 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: il tuo ID progetto Google Cloud .
  • 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 dei plug-in Data Cloud: 
    codex plugin marketplace add GoogleCloudPlatform/data-cloud-plugins
  2. Installa il plug-in Spanner: 
    codex plugin install spanner@data-cloud-plugins
  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-cloud-plugins

Claude per computer


1. Apri Claude per computer 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 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 computer.
5. La nuova schermata della chat mostra 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 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 riuscita al server, viene visualizzato uno stato attivo verde.

Cursore


1. Crea la directory .cursor nella root 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 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 radice 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 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, poi su Configura per aprire il file di configurazione.
3. Aggiungi una delle seguenti configurazioni in base al 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 con Antigravity

Puoi connettere Spanner ad Antigravity nei seguenti modi:

  • Utilizzo dello Store MCP
  • Utilizzo di una configurazione personalizzata

MCP Store

Il modo più consigliato per connettersi ad Antigravity è utilizzare lo store MCP 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 nel negozio MCP, le risorse e le skill 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"
      }
    }
  }
}

Una volta configurato il server MCP personalizzato, le risorse e le skill del server Spanner sono disponibili per l'editor.

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • 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.

Connettiti a Spanner utilizzando Data Agent Kit

Google Cloud Data Agent Kit ti consente di gestire il database Spanner ed eseguire query sui dati Spanner nel tuo IDE o agente di programmazione preferito. L'estensione Data Agent Kit funziona con Visual Studio Code e IDE basati su VS Code, mentre il plug-in Data Agent Kit funziona con una serie di agenti di programmazione popolari, tra cui Claude Code e Codex CLI.

Data Agent Kit fornisce funzionalità di individuazione ed esplorazione dei dati, consentendoti di porre domande sui tuoi dati Spanner in linguaggio naturale. Consente di eliminare il cambio di contesto tra gli strumenti a riga di comando di Spanner e l'ambiente di sviluppo.

Per saperne di più, consulta la panoramica di Data Agent Kit.