Gcs

GCS MCP Server

MCP server for Google Cloud Storage operations with fine-grained tool access control. Supports read/write operations on GCS buckets and objects, with configurable tool groups for security and permission management.

Highlights

• Full GCS bucket and object management (list, get, put, copy, delete)
• Fine-grained access control with tool groups (readonly, readwrite, delete)
• Individual tool enable/disable via environment variables
• Multiple authentication methods (service account key file, inline JSON, ADC)
• GCS credential validation with health checks
• Single bucket constraint mode
• TypeScript with strict type checking
• Comprehensive testing (functional, integration, manual)

Capabilities

Tools

Downloading to Local Disk

get_object returns an object's contents inline as UTF-8 text, which is lossy for binary data and impractical for large files or many files at once. For local data-wrangling, use the download tools instead — both stream raw bytes to disk and belong to the readonly toolgroup:

• `download_object` — download a single object to a local file path. Defaults to a unique file under the OS temp directory.
• `download_prefix` — recursively download every object under a prefix to a local directory, preserving the key path structure as subdirectories. Paginates through the full listing, skips directory-placeholder objects (keys ending in /), collects per-object errors without aborting the batch, and returns a manifest:

  {

"destinationDir": "/tmp/gcs-download-my-bucket-1700000000000", "objectCount": 1234, "totalBytes": 5678901, "files": [ { "key": "logs/2024/01/data.json", "localPath": "/tmp/.../01/data.json", "size": 1234 } ], "filesTruncated": true, "errors": [] }

The inline files list is capped (maxInlineEntries, default 100), but objectCount and totalBytes always reflect the full download. When destinationDir is omitted it defaults to a unique folder under the OS temp directory.

Uploading from Local Disk

put_object takes the object content inline as a string argument, which routes every byte through the model context and requires base64 for binary data — impractical for large files or bulk uploads. For uploading files or folders without consuming context, use the local-path upload tools instead. Both stream raw bytes directly from disk to GCS server-side, returning only metadata. They belong to the readwrite toolgroup, so read-only deployments never gain them.

• `put_object_from_path` — upload a single local file by streaming it from a filesystem path. Content type is auto-detected from the file extension (override with contentType). Binary files (images, archives) work without base64. Returns { bucket, key, sourcePath, size, etag, generation }.
• `upload_prefix` — recursively upload every file under a local directory, preserving the directory structure as key paths beneath a destination prefix. Symbolic links to files are followed and uploaded (links to directories are skipped to avoid cycles), per-file failures are collected without aborting the batch, and it returns a manifest:

  {

"bucket": "my-bucket", "sourceDir": "/tmp/exports", "destPrefix": "uploads/", "objectCount": 1234, "totalBytes": 5678901, "files": [ { "localPath": "/tmp/exports/01/data.json", "key": "uploads/01/data.json", "size": 1234 } ], "filesTruncated": true, "errors": [] }

The inline files list is capped (maxInlineEntries, default 100), but objectCount and totalBytes always reflect the full upload. When destPrefix is omitted, files upload to the bucket root.

Resources

Tool Groups

Control which tools are available via the GCS_ENABLED_TOOLGROUPS environment variable:

Examples:

• GCS_ENABLED_TOOLGROUPS="readonly" - Only read operations
• GCS_ENABLED_TOOLGROUPS="readonly,readwrite" - Read and write, no deletes
• GCS_ENABLED_TOOLGROUPS="readonly,readwrite,delete" - All operations
• Not set - All tools enabled (default)

Individual Tool Control

Fine-grained control over specific tools:

• GCS_ENABLED_TOOLS="list_buckets,get_object" - Only enable these tools
• GCS_DISABLED_TOOLS="delete_bucket,delete_object" - Disable these tools

Single Bucket Mode

Constrain all operations to a specific bucket using GCS_BUCKET:

GCS_BUCKET="my-bucket"

When set:

• All object operations are automatically scoped to this bucket
• Bucket-level tools (list_buckets, create_bucket, delete_bucket, head_bucket) are hidden
• The bucket parameter is automatically injected and hidden from tool inputs
• For copy_object, both source and destination are constrained to the specified bucket

This lets you grant a least-privilege service account that has only object-level access to one bucket, without project-level bucket-listing permission. The startup healthcheck honors this: when GCS_BUCKET is set it validates credentials with an object-scoped probe (storage.objects.list on that bucket) and never calls the project-level bucket list or a bucket-metadata probe. See Required IAM permissions for the exact permissions per mode.

Required IAM permissions

The minimal IAM permissions depend on whether the server is constrained to a single bucket (GCS_BUCKET) and which tool groups you enable. The startup healthcheck validates credentials within these bounds — it does not require any permission beyond what the table below lists for your mode.

Startup healthcheck

Set SKIP_HEALTH_CHECKS=true to bypass startup validation entirely (disables all credential checks — not recommended).

Per-tool permissions

Beyond the healthcheck, each tool needs the corresponding GCS permission at runtime. Grant only what the tool groups you enable require:

| create_bucket (readwrite) | storage.buckets.create