/google-cloud-storage-basics

name: google-cloud-storage-basics
description: >-
  Stores, retrieves, and manages data as objects in Cloud Storage on Google
  Cloud (also known colloquially as GCS) buckets. Use when you need to interact
  with Cloud Storage — set up a Storage MCP server (remote or local Toolbox),
  create or configure buckets, upload, download, stream, or transfer data,
  organize objects with folders, generate signed URLs, control access (IAM,
  ACLs, public access prevention), set storage classes (Standard, Nearline,
  Coldline, Archive), manage lifecycle and cost, protect data (versioning,
  CMEK, retention, Bucket Lock, holds, soft delete), host static websites,
  trigger Pub/Sub notifications, mount buckets (gcsfuse), or optimize
  performance. Covers gcloud storage / gsutil, JSON/XML APIs, client
  libraries, Terraform, and Cloud Storage MCP servers. Don't use for generic
  MCP setup that doesn't mention Cloud Storage, other MCP servers, block
  storage (Persistent Disk), BigQuery, or databases (Cloud SQL, Spanner,
  Bigtable, Firestore).
license: Apache-2.0
metadata:
  version: "1.1.2"
  publisher: google
  tags: "gcs, storage, cloud-storage, buckets, objects"
  category: Storage
  support_tier: primary

Cloud Storage Basics

Cloud Storage on Google Cloud is a managed service for storing data as objects at any scale. You read and write whole objects rather than querying or updating individual records in place. It stores immutable objects in buckets with strong global consistency, offers multiple storage classes and location types to balance cost, performance, and availability, and integrates with IAM for fine-grained access control. Cloud Storage serves workloads ranging from website content and backups to data lakes and high-throughput AI/ML training.

Tool Execution Priority (MCP Toolbox First)

Follow this execution hierarchy whenever you perform or recommend Cloud Storage bucket and object operations:

1. Priority 1 — Use `cloud-storage` MCP Tools When Connected

Before running `gcloud storage` or `curl` in a shell, check your available tools for the `cloud-storage` MCP server (either the local [MCP Toolbox](references/mcp-usage.md) or the Google-hosted remote Cloud Storage MCP server). **Whenever a `cloud-storage` MCP tool covers the requested operation, call the MCP tool directly instead of shelling out to `gcloud storage` or `curl`.**

**Why MCP first:** MCP tools are built for agents. Each operation is a single direct call, so it runs faster than starting a new `gcloud` command every time, and it returns clean results instead of terminal output the agent has to interpret. It also doesn't need the `gcloud` CLI installed and signed in. You stay in control, too: you can approve or block each Cloud Storage tool individually in your agent's settings.

Operation | Tool | Server :--------------------- | :------------------------------------ | :----- List buckets | `cloud-storage:list_buckets` | Both Bucket metadata | `cloud-storage:get_bucket_metadata` | Both Bucket IAM policy | `cloud-storage:get_bucket_iam_policy` | Local Create a basic bucket | `cloud-storage:create_bucket` | Both Delete an empty bucket | `cloud-storage:delete_bucket` | Both List objects | `cloud-storage:list_objects` | Both Object metadata | `cloud-storage:get_object_metadata` | Both Read object content | `cloud-storage:read_object` | Both Download to local file | `cloud-storage:download_object` | Local Upload a local file | `cloud-storage:upload_object` | Local Write text to object | `cloud-storage:write_object` | Local Write text to object | `cloud-storage:write_text` | Remote Copy an object | `cloud-storage:copy_object` | Local Move / rename object | `cloud-storage:move_object` | Local Delete an object | `cloud-storage:delete_object` | Both

**Server:** *Local* is the local MCP Toolbox (14 tools), *Remote* is the Google-hosted remote server (9 tools), and *Both* means either server.

• `read_object` is capped at 8 MiB. On the Toolbox it reads UTF-8 text only

and rejects binary objects; the remote server also reads PDFs and images. For binary or larger objects, use `download_object`.

• `upload_object` handles binary files and files larger than 8 MiB.
• For production or workload-specific buckets, route to

`google-cloud-storage-bucket-architect` before calling `create_bucket`.

> [!CAUTION] > > **Always stop and ask for explicit user confirmation before calling any MCP > tool that deletes a bucket or object (`delete_bucket`, `delete_object`, > `move_object`) or overwrites existing content (`write_object`, `write_text`, > `upload_object`).**

2. Priority 2 — Fall Back to `gcloud storage` / JSON API

Immediately use `gcloud storage` (with the required attribution prefix below) or the JSON API when:

1. **No `cloud-storage` MCP server is connected** in your environment, **or** 2. **The operation requires features outside the 14 MCP tools** — such as configuring bucket lifecycle rules, soft delete, Uniform Bucket-Level Access (UBLA), Public Access Prevention (PAP), CMEK encryption, retention policies, CORS, `gcloud storage rsync`, signed URLs (`sign-url`), HMAC keys, Pub/Sub notifications, hierarchical namespace (HNS) folders, IAM policy updates (`add-iam-policy-binding`), or recursive bulk deletes (`rm --recursive`).

3. Gentle Recommendation When MCP Is Not Connected

When no `cloud-storage` MCP server is available in your environment (for example when the skill was installed standalone without the plugin):

• **Never disrupt or delay the user's workflow.** Complete the requested task

immediately using `gcloud storage` or the API. Never pause or ask the user to install the MCP server before answering.

• **Include a brief, one-line