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 la CLI Gemini. Questa estensione elimina la necessità di configurare una connessione server separata. Puoi configurare Gemini Code Assist per utilizzare la CLI Gemini, che offre vantaggi di configurazione simili nel tuo IDE. Per saperne di più, consulta Estensione della CLI Gemini - 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 dell'interfaccia a riga di comando di Gemini in Spanner

L'integrazione di Spanner con la CLI Gemini avviene tramite un'estensione open source che offre funzionalità aggiuntive rispetto alla connessione standard di MCP Toolbox. L'estensione offre una procedura di installazione e un insieme di strumenti, oltre a fornire informazioni dettagliate su installazione, configurazione ed esempi di utilizzo. Se utilizzi l'estensione Gemini CLI, non è necessario installare MCP Toolbox. Per saperne di più, consulta Estensione della CLI Gemini - 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 Spanner?
execute_sql Inserisci i dati di test nella tabella dei prodotti.
execute_sql_dql Quali prodotti della categoria elettronica vengono venduti in America?

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 .

Configurare 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.

Installare 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/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

  2. Rendi eseguibile il file binario:

    chmod +x toolbox

  3. Verifica l'installazione:

    ./toolbox --version

Configurare lo strumento dell'agente

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

Interfaccia a riga di comando di Gemini

  1. Installa l'interfaccia a riga di comando di Gemini.
  2. Installa l'estensione Spanner per Gemini CLI dal 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 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 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. Il valore predefinito è googlesql se non definito.
  4. Avvia l'interfaccia a riga di comando di Gemini in modalità interattiva: 
        gemini
    La CLI carica automaticamente l'estensione Spanner per Gemini CLI e i relativi strumenti, che puoi utilizzare per interagire con il tuo database.

Gemini Code Assist

Ti consigliamo vivamente di configurare Gemini Code Assist in modo che utilizzi l'interfaccia a riga di comando di Gemini, 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à Agent e passa al modello 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 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. Crea il file .mcp.json nella directory principale del progetto, se non esiste.
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"
      }
    }
  }
}

Claude per computer


1. Apri Claude per il 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 il desktop.
5. Nella nuova schermata della 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 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 del 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 per le cascate.
2. Fai clic sull'icona di MCP, quindi 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"
      }
    }
  }
}