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 di Spanner a vari strumenti per sviluppatori che supportano il protocollo Model Context Protocol (MCP).

Ti consigliamo di utilizzare l'estensione Spanner dedicata per Gemini CLI. Questa estensione elimina la necessità di configurare una connessione server separata. 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 e un insieme di strumenti, oltre a fornire informazioni dettagliate sull'installazione, sulla configurazione e sugli esempi di utilizzo. Se utilizzi l'estensione Gemini CLI, non devi installare MCP Toolbox. Per maggiori informazioni, consulta Estensione Gemini CLI - Spanner.

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

Strumenti Esempio di prompt in linguaggio naturale
list_tables Quali tabelle ho nella mia istanza di Spanner?
execute_sql Inserisci i dati di test nella tabella dei prodotti.
execute_sql_dql Quali prodotti della categoria elettronica sono venduti in America?

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 di 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 deve disporre dei seguenti ruoli a livello di database:

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

    • Cloud Spanner Database User (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 lo strumento agente

Questa sezione descrive come configurare vari strumenti per sviluppatori per connetterti all'istanza di Spanner. Seleziona lo strumento agente tra le seguenti opzioni:

Gemini CLI

  1. Installa Gemini CLI.
  2. Installa l'estensione Spanner per Gemini CLI da il repository GitHub utilizzando il seguente comando:
    3.   gemini extensions install https://github.com/gemini-cli-extensions/spanner
  3. Imposta le seguenti variabili di ambiente per connetterti all'istanza di 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: il tuo Google Cloud ID progetto.
    • INSTANCE_NAME: il nome dell'istanza di 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 è a googlesql.
  4. Avvia Gemini CLI in modalità interattiva: 
        gemini
    L'interfaccia a riga di comando carica automaticamente l'estensione Spanner per Gemini CLI e i relativi strumenti, che puoi utilizzare per interagire con il database.

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 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: il tuo Google Cloud ID progetto.
  • INSTANCE_NAME: il nome dell'istanza di 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. Crea il file .mcp.json nella directory principale del progetto, se non esiste.
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"
      }
    }
  }
}

Claude for Desktop


1. Apri Claude for 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 for 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 Cursor 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 di Spanner nel tuo progetto.

Una volta installato il server Spanner nell'MCP Store, le risorse e gli strumenti 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 gli strumenti del server Spanner sono disponibili per l'editor.

Sostituisci quanto segue:

  • PROJECT_ID: il tuo Google Cloud ID progetto.
  • INSTANCE_NAME: il nome dell'istanza di 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.