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. Il toolbox supporta l'autenticazione OAuth2 e OIDC e si integra con OpenTelemetry per l'osservabilità. L'integrazione della casella degli strumenti Cloud Storage ti consente di utilizzare un LLM per eseguire le seguenti azioni:

• Creare, elencare ed eliminare bucket.
• Recupera i metadati di bucket e oggetti.
• Recupera i criteri IAM (Identity and Access Management) sui tuoi bucket.
• Leggere, scrivere, caricare e scaricare oggetti.
• Copia o sposta gli 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 del toolbox, consulta il repository GitHub MCP di Cloud Storage.

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 .

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 i bucket vuoti: Storage Admin (roles/storage.admin)
   • Per elencare gli oggetti, leggerli, ottenere i metadati degli oggetti o i metadati dei bucket: Storage Object Viewer (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: Storage Object Admin (roles/storage.objectAdmin)

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

Contattare 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 anziché installare il server direttamente dal catalogo integrato di MCP Store.

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

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 di npm Download e installazione di Node.js e npm.
2. Apri Antigravity e vai allo store MCP 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 il tuo ID progetto e salva:

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

Installa MCP Toolbox

Il toolbox è un server Model Context Protocol (MCP) open source che viene eseguito localmente sul tuo computer. Il server locale gestisce la comunicazione tra il tuo 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 tuo 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 Toolbox.

Configurare client e connessioni

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

Claude Code

1. Installa Claude Code.
2. Crea un file .mcp.json nella directory principale 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 binario toolbox.
   • CLOUD_STORAGE_PROJECT: La variabile di ambiente che specifica l' Google Cloud ID progetto.
   • PROJECT_ID: l'ID progetto Google Cloud .
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 binario toolbox.
   • CLOUD_STORAGE_PROJECT: La variabile di ambiente che specifica l' Google Cloud ID progetto.
   • PROJECT_ID: l'ID progetto Google Cloud .
4. Riavvia Claude Desktop.
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 MCP Servers.
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 binario toolbox.
   • CLOUD_STORAGE_PROJECT: La variabile di ambiente che specifica l' Google Cloud ID progetto.
   • PROJECT_ID: l'ID progetto Google Cloud .

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 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 binario toolbox.
   • CLOUD_STORAGE_PROJECT: La variabile di ambiente che specifica l' Google Cloud ID progetto.
   • PROJECT_ID: l'ID progetto Google Cloud .
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 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 binario toolbox.
   • CLOUD_STORAGE_PROJECT: La variabile di ambiente che specifica l' Google Cloud ID progetto.
   • PROJECT_ID: l'ID progetto Google Cloud .
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 binario toolbox.
   • CLOUD_STORAGE_PROJECT: La variabile di ambiente che specifica l' Google Cloud ID progetto.
   • PROJECT_ID: l'ID progetto Google Cloud .

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 facoltativi per prefisso e delimitatore.
• get_bucket_metadata: restituisce i metadati per un bucket.
• get_bucket_iam_policy: restituisce le associazioni di policy 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). 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 in modo atomico un oggetto all'interno dello stesso bucket.
• delete_object: elimina un oggetto.