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

  1. Nella console Cloud de Confiance , nella pagina di selezione del progetto, seleziona o crea un progetto Cloud de Confiance by S3NS .

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

  3. Abilita l'API BigQuery nel Cloud de Confiance progetto.

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

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

  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 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 esempio v0.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 esempio v0.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 esempio v0.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 esempio v0.7.0.

  2. Rendi eseguibile il file binario:

    chmod +x toolbox
    
  3. 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

  1. Installa Claude Code.
  2. Crea un file .mcp.json nella root del progetto, se non esiste.
  3. 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"
                  }
                }
              }
            }
            
  4. Riavvia Claude Code per caricare le nuove impostazioni. Quando si riapre, lo strumento indica che il server MCP configurato è stato rilevato.

Claude desktop

  1. Apri Claude Desktop e vai a Impostazioni.
  2. Nella scheda Sviluppatore, fai clic su Modifica configurazione per aprire il file di configurazione.
  3. 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"
                  }
                }
              }
            }
            
  4. Riavvia Claude 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 tocca l'icona Server MCP.
  2. Tocca Configura server MCP per aprire il file di configurazione.
  3. 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

  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 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"
                  }
                }
              }
            }
            
  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 una directory .vscode nella radice del progetto se non esiste.
  2. Crea il file .vscode/mcp.json se non esiste e aprilo.
  3. 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"
                  }
                }
              }
            }
            
  4. Ricarica la finestra di VS Code. L'estensione compatibile con MCP rileva automaticamente la configurazione e avvia il server.

Windsurf

  1. Apri Windsurf e vai all'assistente Cascade.
  2. Fai clic sull'icona di MCP, quindi su Configura per aprire il file di configurazione.
  3. 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.