Utilizzare BigQuery con MCP, Gemini CLI e altri agenti
Questa guida mostra come utilizzare MCP Toolbox for Databases per collegare il progetto BigQuery a una serie di ambienti di sviluppo integrati (IDE) e strumenti per sviluppatori. Utilizza il Model Context Protocol (MCP), un protocollo aperto per collegare modelli linguistici di grandi dimensioni (LLM) a origini dati come BigQuery, consentendoti di eseguire query SQL e interagire con il tuo progetto direttamente dagli strumenti esistenti.
Se utilizzi la CLI Gemini, puoi utilizzare le estensioni BigQuery. Per scoprire come fare, consulta Sviluppare con Gemini CLI. Se prevedi di creare strumenti personalizzati per la CLI Gemini, continua a leggere.
Questa guida mostra la procedura di connessione per i seguenti IDE:
- Cursore
- Windsurf (in precedenza Codeium)
- Visual Studio Code (Copilot)
- Cline (estensione VS Code)
- Claude desktop
- Codice Claude
Prima di iniziare
Nella console Cloud de Confiance , nella pagina di selezione del progetto, seleziona o crea un progetto Cloud de Confiance by S3NS .
Verifica che la fatturazione sia attivata per il tuo progetto Cloud de Confiance .
Configura i ruoli e le autorizzazioni richiesti per completare questa attività. Per connetterti al progetto, devi disporre del ruolo Utente BigQuery (
roles/bigquery.user
), del ruolo Visualizzatore dati BigQuery (roles/bigquery.dataViewer
) o di autorizzazioni IAM equivalenti.Configura le credenziali predefinite dell'applicazione (ADC) per il tuo ambiente.
Installare la casella degli strumenti MCP
Non è necessario installare MCP Toolbox se prevedi di utilizzare solo le estensioni della CLI BigQuery Gemini, in quanto includono le funzionalità del server richieste. Per altri IDE e strumenti, segui i passaggi descritti in questa sezione per installare MCP Toolbox.
Il toolbox funge da server Model Context Protocol (MCP) open source che si trova tra l'IDE e BigQuery, fornendo un piano di controllo sicuro ed efficiente per i tuoi strumenti di AI.
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 V0.7.0 o successive:
linux/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/linux/amd64/toolbox
Sostituisci
VERSION
con la versione di MCP Toolbox, ad esempiov0.7.0
.macOS darwin/arm64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/arm64/toolbox
Sostituisci
VERSION
con la versione di MCP Toolbox, ad esempiov0.7.0
.macOS darwin/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/amd64/toolbox
Sostituisci
VERSION
con la versione di MCP Toolbox, ad esempiov0.7.0
.windows/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/windows/amd64/toolbox
Sostituisci
VERSION
con la versione di MCP Toolbox, ad esempiov0.7.0
.Rendi eseguibile il file binario:
chmod +x toolbox
Verifica l'installazione:
./toolbox --version
Configurare client e connessioni
Questa sezione spiega come connettere BigQuery ai tuoi strumenti.
Se utilizzi la CLI Gemini autonoma, non devi installare o configurare MCP Toolbox, poiché le estensioni raggruppano le funzionalità del server richieste.
Per altri strumenti e IDE compatibili con MCP, devi prima installare MCP Toolbox.
Codice Claude
- Installa Claude Code.
- Crea un file
.mcp.json
nella root del progetto, se non esiste. - Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi
valori e salva:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } }
- Riavvia Claude Code per caricare le nuove impostazioni. Quando si riapre, lo strumento indica che il server MCP configurato è stato rilevato.
Claude desktop
- Apri Claude Desktop e vai a Impostazioni.
- Nella scheda Sviluppatore, fai clic su Modifica configurazione per aprire il file di configurazione.
- Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi
valori e salva:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } }
- Riavvia Claude Desktop.
- Nella nuova schermata della chat viene visualizzata un'icona a forma di martello (MCP) con il nuovo server MCP.
Cline
- Apri l'estensione Cline in VS Code e tocca l'icona Server MCP.
- Tocca Configura server MCP per aprire il file di configurazione.
- Aggiungi la seguente configurazione, sostituisci le variabili di ambiente
con i tuoi valori e salva:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } }
Dopo la connessione riuscita del server, viene visualizzato uno stato attivo verde.
Cursore
- Crea la directory
.cursor
nella root del progetto se non esiste. - Crea il file
.cursor/mcp.json
se non esiste e aprilo. - Aggiungi la seguente configurazione, sostituisci le variabili di ambiente
con i tuoi valori e salva:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } }
- Apri Cursore e vai a Impostazioni > Impostazioni cursore > MCP. Quando il server si connette, viene visualizzato uno stato attivo verde.
Visual Studio Code (Copilot)
- Apri
VS Code
e crea una directory
.vscode
nella radice del progetto se non esiste. - Crea il file
.vscode/mcp.json
se non esiste e aprilo. - Aggiungi la seguente configurazione, sostituisci le variabili di ambiente
con i tuoi valori e salva:
{ "servers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } }
- Ricarica la finestra di VS Code. L'estensione compatibile con MCP rileva automaticamente la configurazione e avvia il server.
Windsurf
- Apri Windsurf e vai all'assistente Cascade.
- Fai clic sull'icona di MCP, quindi su Configura per aprire il file di configurazione.
- Aggiungi la seguente configurazione, sostituisci le variabili di ambiente
con i tuoi valori e salva:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } }
Nota:la variabile di ambiente
BIGQUERY_PROJECT
specifica l'ID progetto Cloud de Confiance predefinito da utilizzare per MCP Toolbox. Tutte le operazioni BigQuery, come l'esecuzione di query, vengono eseguite all'interno di questo progetto.
Utilizzare gli strumenti
Il tuo strumento di AI è ora connesso a BigQuery tramite MCP. Prova a chiedere all'assistente AI di elencare le tabelle, creare una tabella o definire ed eseguire altre istruzioni SQL.
Sono disponibili i seguenti strumenti per il LLM:
- analyze_contribution: esegui l'analisi del contributo, chiamata anche analisi dei principali fattori.
- ask_data_insights: esegui l'analisi dei dati, ottieni approfondimenti o rispondi a domande complesse sui contenuti delle tabelle BigQuery.
- execute_sql: esegui l'istruzione SQL.
- forecast: prevede i dati delle serie temporali.
- get_dataset_info: recupera i metadati del set di dati.
- get_table_info: recupera i metadati della tabella.
- list_dataset_ids: elenca i set di dati.
- list_table_ids: elenca le tabelle.
- search_catalog: cerca una tabella utilizzando il linguaggio naturale.