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 skill sottostanti direttamente al suo interno, 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 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 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 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 competenze disponibili, consulta la pagina Competenze di Spanner su GitHub.
Prima di iniziare
Nella console Google Cloud , nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud .
Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .
Configurare l'istanza Spanner
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.
Configura le Credenziali predefinite dell'applicazione (ADC) per il tuo ambiente.
Installa MCP Toolbox
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
Rendi eseguibile il file binario:
chmod +x toolboxVerifica 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 tra le seguenti opzioni:
Gemini CLI
- Installa la Gemini CLI.
- Installa l'estensione Spanner per Gemini CLI dal
repository GitHub utilizzando il seguente comando:
gemini extensions install https://github.com/gemini-cli-extensions/spanner
- 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"
- 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
googlesqlopostgresql. Se non definito, il valore predefinito ègooglesql.
- Avvia Gemini CLI in modalità interattiva:
gemini
La CLI carica automaticamente l'estensione Spanner per Gemini CLI e le relative competenze, che puoi utilizzare per interagire con il tuo database.
Nella Gemini CLI, utilizza il comando
/extensionsper verificare che l'estensione sia installata.
Gemini Code Assist
Ti consigliamo vivamente di configurare Gemini Code Assist per utilizzare 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à Agent 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.
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
- Installa Claude Code.
- 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"
- 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
googlesqlopostgresql. Se non definito, il valore predefinito ègooglesql.
- Avvia l'agente:
claude
- Installa il plug-in:
/plugin install spanner@claude-plugins-official
Codex
- Installa il marketplace Data Agent Kit:
codex plugin marketplace add GoogleCloudPlatform/data-agent-kit
- Installa il plug-in Spanner:
codex plugin install spanner@data-agent-kit
- Configura le variabili di ambiente per connetterti alla tua istanza Spanner:
export SPANNER_PROJECT="PROJECT_ID" export SPANNER_INSTANCE="INSTANCE_NAME" export SPANNER_DATABASE="DATABASE_NAME" export SPANNER_DIALECT="DIALECT_NAME"
- 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
googlesqlopostgresql. Se non definito, il valore predefinito ègooglesql.
- Facoltativo. Aggiorna il marketplace:
codex plugin marketplace upgrade data-agent-kit
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 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 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 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 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 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"
}
}
}
}
Contattare 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 l'MCP Store integrato.
- Apri Antigravity e il pannello dell'agente dell'editor.
- Fai clic sull'icona Menu nella parte superiore del riquadro e seleziona Server MCP.
- Individua Spanner nell'elenco dei server disponibili e fai clic su Installa.
- 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 competenze del server sono disponibili per l'editor.
Configurazione personalizzata
Per connetterti a un server MCP personalizzato, segui questi passaggi:
- Apri Antigravity e il pannello dell'agente dell'editor.
- Fai clic sull'icona Menu nella parte superiore del riquadro e seleziona Server MCP.
- Fai clic su Gestisci server MCP > Visualizza configurazione non elaborata per aprire il file
mcp_config.json. - 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 competenze 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. Accettagooglesqlopostgresql. Se non specifichi un dialetto, il valore predefinito ègooglesql.