Connettere i LLM a Cloud Storage con MCP

Questa guida mostra come connettere Cloud Storage agli ambienti di sviluppo integrati (IDE) e agli strumenti per sviluppatori. Per farlo, esegui un server MCP locale sulla tua macchina utilizzando MCP Toolbox for Databases.

MCP Toolbox for Databases è un repository open source che contiene connettori per database e datastore, tra cui Cloud Storage, BigQuery, AlloyDB, Spanner e Cloud SQL. La toolbox supporta l'autenticazione OAuth2 e OIDC e si integra con OpenTelemetry per l'osservabilità. L'integrazione della toolbox di Cloud Storage ti consente di utilizzare un LLM per eseguire le seguenti azioni:

• Creare, elencare ed eliminare bucket.
• Recuperare i metadati di bucket e oggetti.
• Recuperare i criteri IAM (Identity and Access Management) sui bucket.
• Leggere, scrivere, caricare e scaricare oggetti.
• Copiare o spostare oggetti.

Questa guida illustra la procedura di connessione per i seguenti IDE e strumenti:

• Cursore
• Windsurf (in precedenza Codeium)
• Visual Studio Code (Copilot)
• Cline (estensione VS Code)
• Claude desktop
• Claude code
• Antigravity

Nota: l'integrazione di Cloud Storage è disponibile in MCP Toolbox versione 1.2.0 o successive. Se vuoi utilizzare il server MCP locale di Cloud Storage come server autonomo al di fuori della toolbox, consulta il repository GitHub di Cloud Storage MCP.

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.

3. Abilita l'API Storage nel Google Cloud progetto.

4. 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 bucket o progetto:

   • Per elencare i bucket, creare bucket ed eliminare bucket vuoti: Amministratore Storage (roles/storage.admin)
   • Per elencare gli oggetti, leggere gli oggetti, recuperare i metadati degli oggetti o i metadati dei bucket: Visualizzatore oggetti Storage (roles/storage.objectViewer)
   • Per scrivere contenuti in un oggetto o caricare un oggetto: Creatore oggetti Storage (roles/storage.objectCreator)
   • Per copiare, spostare o eliminare oggetti: Amministratore oggetti Storage (roles/storage.objectAdmin)

5. Configura le Credenziali predefinite dell'applicazione (ADC) per il tuo ambiente.

Connettersi ad Antigravity

Collega Cloud Storage ad Antigravity utilizzando una configurazione personalizzata. In questo contesto, un server MCP personalizzato è un server che configuri manualmente modificando il file di configurazione (ad esempio mcp_config.json). Questa configurazione manuale viene utilizzata al posto dell'installazione del server direttamente dal catalogo MCP Store integrato.

Nota: non è necessario scaricare il file binario di MCP Toolbox per utilizzare questo metodo.

Per configurare un server MCP personalizzato:

1. Verifica che npx sia installato e configurato correttamente sul tuo sistema eseguendo npx --version nel terminale. Se devi installare Node.js, che include npx, consulta la guida npm Scaricare e installare Node.js e npm.
2. Apri Antigravity e vai a MCP Store utilizzando il menu a discesa "..." nella parte superiore del riquadro dell'agente dell'editor.
3. Per aprire il file mcp_config.json, fai clic su Server MCP e poi su Gestisci server MCP > Visualizza configurazione non elaborata.
4. Aggiungi la seguente configurazione, sostituisci il segnaposto con l'ID progetto e salva:

   {
     "mcpServers": {
       "storage": {
         "command": "npx",
         "args": ["-y","@toolbox-sdk/server","--prebuilt","cloud-storage","--stdio"],
         "env": {
             "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
         }
       }
     }
   }
   

Installare MCP Toolbox

La toolbox è un server Model Context Protocol (MCP) open source che viene eseguito localmente sulla tua macchina. Il server locale gestisce la comunicazione tra l'IDE e Cloud Storage. Questa connessione fornisce un ambiente 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 sistema operativo e all'architettura della CPU. Devi utilizzare MCP Toolbox versione 1.2.0 o successive:

   linux/amd64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/linux/amd64/toolbox
   

   Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v1.2.0.

   macOS darwin/arm64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/darwin/arm64/toolbox
   

   Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v1.2.0.

   macOS darwin/amd64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/darwin/amd64/toolbox
   

   Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v1.2.0.

   windows/amd64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/windows/amd64/toolbox
   

   Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v1.2.0.

2. Rendi eseguibile il file binario:

   chmod +x toolbox
   

3. Verifica l'installazione:

   ./toolbox --version
   

Per configurare la toolbox con un'immagine container o Homebrew, consulta la pagina Installare la toolbox.

Configurare client e connessioni

Questa sezione descrive come connettere Cloud Storage ai tuoi strumenti dopo aver installato il MCP Toolbox.

Claude code

1. Installa Claude Code.
2. Crea un file .mcp.json nella directory root del progetto, se non esiste.
3. Aggiungi la configurazione, sostituisci i segnaposto con i tuoi valori e salva:

           {
             "mcpServers": {
               "storage": {
                 "command": "./PATH/TO/toolbox",
                 "args": ["--prebuilt","cloud-storage","--stdio"],
                 "env": {
                   "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
                 }
               }
             }
           }
           

   Sostituisci le seguenti variabili con i tuoi valori:
   • ./PATH/TO/toolbox: il percorso del file binario toolbox.
   • CLOUD_STORAGE_PROJECT: la variabile di ambiente che specifica l' Google Cloud ID progetto.
   • PROJECT_ID: l' Google Cloud ID progetto.
4. Riavvia Claude Code per caricare le nuove impostazioni. Quando Claude Code si riapre, l'applicazione rileva il server MCP configurato.

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 i segnaposto con i tuoi valori e salva:

           {
             "mcpServers": {
               "storage": {
                 "command": "./PATH/TO/toolbox",
                 "args": ["--prebuilt","cloud-storage","--stdio"],
                 "env": {
                   "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
                 }
               }
             }
           }
           

   Sostituisci le seguenti variabili con i tuoi valori:
   • ./PATH/TO/toolbox: il percorso del file binario toolbox.
   • CLOUD_STORAGE_PROJECT: la variabile di ambiente che specifica l' Google Cloud ID progetto.
   • PROJECT_ID: l' Google Cloud ID progetto.
4. Riavvia Claude Desktop.
5. La nuova schermata di 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. Fai clic su Configura server MCP per aprire il file di configurazione.
3. Aggiungi la seguente configurazione, sostituisci i segnaposto con i tuoi valori e salva:

           {
             "mcpServers": {
               "storage": {
                 "command": "./PATH/TO/toolbox",
                 "args": ["--prebuilt","cloud-storage","--stdio"],
                 "env": {
                   "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
                 }
               }
             }
           }
           

   Sostituisci le seguenti variabili con i tuoi valori:
   • ./PATH/TO/toolbox: il percorso del file binario toolbox.
   • CLOUD_STORAGE_PROJECT: la variabile di ambiente che specifica l' Google Cloud ID progetto.
   • PROJECT_ID: l' Google Cloud ID progetto.

Dopo che il server si è connesso correttamente, viene visualizzato uno stato attivo verde.

Cursore

1. Crea la directory .cursor nella directory root del progetto, se non esiste.
2. Crea il file .cursor/mcp.json se non esiste e aprilo.
3. Aggiungi la seguente configurazione, sostituisci i segnaposto con i tuoi valori e salva:

           {
             "mcpServers": {
               "storage": {
                 "command": "./PATH/TO/toolbox",
                 "args": ["--prebuilt","cloud-storage","--stdio"],
                 "env": {
                   "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
                 }
               }
             }
           }
           

   Sostituisci le seguenti variabili con i tuoi valori:
   • ./PATH/TO/toolbox: il percorso del file binario toolbox.
   • CLOUD_STORAGE_PROJECT: la variabile di ambiente che specifica l' Google Cloud ID progetto.
   • PROJECT_ID: l' Google Cloud ID progetto.
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 una directory .vscode nella directory root del progetto, se non esiste.
2. Crea il file .vscode/mcp.json se non esiste e aprilo.
3. Aggiungi la seguente configurazione, sostituisci i segnaposto con i tuoi valori e salva:

           {
             "mcpServers": {
               "storage": {
                 "command": "./PATH/TO/toolbox",
                 "args": ["--prebuilt","cloud-storage","--stdio"],
                 "env": {
                   "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
                 }
               }
             }
           }
           

   Sostituisci le seguenti variabili con i tuoi valori:
   • ./PATH/TO/toolbox: il percorso del file binario toolbox.
   • CLOUD_STORAGE_PROJECT: la variabile di ambiente che specifica l' Google Cloud ID progetto.
   • PROJECT_ID: l' Google Cloud ID progetto.
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 MCP, quindi su Configura per aprire il file di configurazione.
3. Aggiungi la seguente configurazione, sostituisci i segnaposto con i tuoi valori e salva:

           {
             "mcpServers": {
               "storage": {
                 "command": "./PATH/TO/toolbox",
                 "args": ["--prebuilt","cloud-storage","--stdio"],
                 "env": {
                   "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
                 }
               }
             }
           }
           

   Sostituisci le seguenti variabili con i tuoi valori:
   • ./PATH/TO/toolbox: il percorso del file binario toolbox.
   • CLOUD_STORAGE_PROJECT: la variabile di ambiente che specifica l' Google Cloud ID progetto.
   • PROJECT_ID: l' Google Cloud ID progetto.

Strumenti predefiniti

Dopo aver connesso MCP Toolbox a Cloud Storage, l'agente utilizza i seguenti strumenti predefiniti:

• list_buckets: elenca i bucket Cloud Storage nel progetto configurato.
• list_objects: elenca gli oggetti in un bucket con filtri di prefisso e delimitatore facoltativi.
• get_bucket_metadata: restituisce i metadati di un bucket.
• get_bucket_iam_policy: restituisce i binding dei criteri IAM per un bucket.
• get_object_metadata: restituisce i metadati di un oggetto.
• read_object: legge un oggetto di testo UTF-8 (o un intervallo di byte). Il limite è di 8 MiB; gli oggetti binari vengono rifiutati.
• download_object: scarica un oggetto in un percorso locale.
• create_bucket: crea un bucket nel progetto configurato.
• delete_bucket: elimina un bucket vuoto.
• upload_object: carica un file locale in un oggetto.
• write_object: scrive contenuti di testo direttamente in un oggetto.
• copy_object: copia un oggetto in un oggetto di destinazione.
• move_object: rinomina atomicamente un oggetto all'interno dello stesso bucket.
• delete_object: elimina un oggetto.