Connect LLMs to Cloud Storage with MCP

This guide shows you how to connect Cloud Storage to Integrated Development Environments (IDEs) and developer tools. To do this, you run a local MCP server on your machine by using the MCP Toolbox for Databases.

The MCP Toolbox for Databases is an open-source repository that contains connectors for databases and datastores, including Cloud Storage, BigQuery, AlloyDB, Spanner, and Cloud SQL. The toolbox supports OAuth2 and OIDC authentication, and integrates with Open Telemetry for observability. The Cloud Storage toolbox integration lets you use an LLM to perform the following actions:

• Create, list, and delete buckets.
• Get bucket and object metadata.
• Get Identity and Access Management (IAM) policies on your buckets.
• Read, write, upload, and download objects.
• Copy or move objects.

This guide demonstrates the connection process for the following IDEs and tools:

• Cursor
• Windsurf (formerly Codeium)
• Visual Studio Code (Copilot)
• Cline (VS Code extension)
• Claude desktop
• Claude code
• Antigravity

Note: The Cloud Storage integration is available in MCP Toolbox version 1.2.0 or later. If you want to use the Cloud Storage local MCP server as a standalone server outside of the toolbox, see the Cloud Storage MCP GitHub repository.

Before you begin

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

2. Make sure that billing is enabled for your Google Cloud project.

3. Enable the Cloud Storage API in the Google Cloud project.

4. Configure the required roles and permissions to complete this task. The user invoking the LLM agents needs the following roles at the bucket or project level:

   • To list buckets, create buckets, and delete empty buckets: Storage Admin (roles/storage.admin)
   • To list objects, read objects, get object metadata, or bucket metadata: Storage Object Viewer (roles/storage.objectViewer)
   • To write content to an object or upload an object: Storage Object Creator (roles/storage.objectCreator)
   • To copy, move, or delete objects: Storage Object Admin (roles/storage.objectAdmin)

5. Configure Application Default Credentials (ADC) for your environment.

Connect with Antigravity

You connect Cloud Storage to Antigravity using a custom configuration. In this context, a custom MCP server is a server that you configure manually by editing your configuration file (such as mcp_config.json). This manual configuration is used instead of installing the server directly from the built-in MCP Store catalog.

Note: You don't need to download the MCP Toolbox binary to use this method.

To configure a custom MCP server, do the following:

1. Verify that npx is installed and properly configured on your system by running npx --version in your terminal. If you need to install Node.js, which includes npx, see the npm Downloading and installing Node.js and npm guide.
2. Open Antigravity and navigate to the MCP store using the "..." drop-down at the top of the editor's agent panel.
3. To open the mcp_config.json file, click MCP Servers and then click Manage MCP Servers > View raw config.
4. Add the following configuration, replace the placeholder with your project ID, and save:

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

Install the MCP Toolbox

The toolbox is an open-source Model Context Protocol (MCP) server that runs locally on your machine. The local server manages communication between your IDE and Cloud Storage. This connection provides a secure and efficient environment for your AI tools.

1. Download the latest version of the MCP Toolbox as a binary. Select the binary corresponding to your operating system (OS) and CPU architecture. You must use MCP Toolbox version 1.2.0 or later:

   linux/amd64

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

   Replace VERSION with the MCP Toolbox version—for example, v1.2.0.

   macOS darwin/arm64

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

   Replace VERSION with the MCP Toolbox version—for example, v1.2.0.

   macOS darwin/amd64

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

   Replace VERSION with the MCP Toolbox version—for example, v1.2.0.

   windows/amd64

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

   Replace VERSION with the MCP Toolbox version—for example, v1.2.0.

2. Make the binary executable:

   chmod +x toolbox
   

3. Verify the installation:

   ./toolbox --version
   

To set up the toolbox with a container image or Homebrew, see the Install Toolbox page.

Set up clients and connections

This section describes how to connect Cloud Storage to your tools after you install the MCP Toolbox.

Claude code

1. Install Claude Code.
2. Create a .mcp.json file in your project root, if it doesn't exist.
3. Add the configuration, replace the placeholders with your values, and save:

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

   Replace the following variables with your values:
   • ./PATH/TO/toolbox: The path to your toolbox binary.
   • CLOUD_STORAGE_PROJECT: The environment variable specifying the Google Cloud Project ID.
   • PROJECT_ID: Your Google Cloud project ID.
4. Restart Claude Code to load the new settings. When Claude Code reopens, the application detects the configured MCP server.

Claude desktop

1. Open Claude Desktop and navigate to Settings.
2. In the Developer tab, click Edit Config to open the configuration file.
3. Add the configuration, replace the placeholders with your values, and save:

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

   Replace the following variables with your values:
   • ./PATH/TO/toolbox: The path to your toolbox binary.
   • CLOUD_STORAGE_PROJECT: The environment variable specifying the Google Cloud Project ID.
   • PROJECT_ID: Your Google Cloud project ID.
4. Restart Claude Desktop.
5. The new chat screen displays a hammer (MCP) icon with the new MCP server.

Cline

1. Open the Cline extension in VS Code and click the MCP Servers icon.
2. Click Configure MCP Servers to open the configuration file.
3. Add the following configuration, replace the placeholders with your values, and save:

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

   Replace the following variables with your values:
   • ./PATH/TO/toolbox: The path to your toolbox binary.
   • CLOUD_STORAGE_PROJECT: The environment variable specifying the Google Cloud Project ID.
   • PROJECT_ID: Your Google Cloud project ID.

A green active status appears after the server connects successfully.

Cursor

1. Create the .cursor directory in your project root if it doesn't exist.
2. Create the .cursor/mcp.json file if it doesn't exist and open it.
3. Add the following configuration, replace the placeholders with your values, and save:

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

   Replace the following variables with your values:
   • ./PATH/TO/toolbox: The path to your toolbox binary.
   • CLOUD_STORAGE_PROJECT: The environment variable specifying the Google Cloud Project ID.
   • PROJECT_ID: Your Google Cloud project ID.
4. Open Cursor and navigate to Settings > Cursor Settings > MCP. A green active status appears when the server connects.

Visual Studio Code (Copilot)

1. Open VS Code and create a .vscode directory in your project root if it does not exist.
2. Create the .vscode/mcp.json file if it doesn't exist, and open it.
3. Add the following configuration, replace the placeholders with your values, and save:

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

   Replace the following variables with your values:
   • ./PATH/TO/toolbox: The path to your toolbox binary.
   • CLOUD_STORAGE_PROJECT: The environment variable specifying the Google Cloud Project ID.
   • PROJECT_ID: Your Google Cloud project ID.
4. Reload the VS Code window. The MCP-compatible extension automatically detects the configuration and starts the server.

Windsurf

1. Open Windsurf and navigate to the Cascade assistant.
2. Click the MCP icon, then click Configure to open the configuration file.
3. Add the following configuration, replace the placeholders with your values, and save:

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

   Replace the following variables with your values:
   • ./PATH/TO/toolbox: The path to your toolbox binary.
   • CLOUD_STORAGE_PROJECT: The environment variable specifying the Google Cloud Project ID.
   • PROJECT_ID: Your Google Cloud project ID.

Prebuilt tools

After you connect the MCP Toolbox to Cloud Storage, your agent uses the following prebuilt tools:

• list_buckets: Lists Cloud Storage buckets in the configured project.
• list_objects: Lists objects in a bucket with optional prefix and delimiter filtering.
• get_bucket_metadata: Returns metadata for a bucket.
• get_bucket_iam_policy: Returns the IAM policy bindings for a bucket.
• get_object_metadata: Returns metadata for an object.
• read_object: Reads a UTF-8 text object (or byte range). Capped at 8 MiB; binary objects are rejected.
• download_object: Downloads an object to a local path.
• create_bucket: Creates a bucket in the configured project.
• delete_bucket: Deletes an empty bucket.
• upload_object: Uploads a local file to an object.
• write_object: Writes text content directly to an object.
• copy_object: Copies an object to a destination object.
• move_object: Atomically renames an object within the same bucket.
• delete_object: Deletes an object.