GCS MCP Server

Note: This package is part of the MCP Servers monorepo. For the latest updates and full source code, visit the GCS MCP Server directory.

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

| Tool | Group | Description | | ---------------------- | --------- | ------------------------------------------------------------------------------- | | list_buckets | readonly | List all GCS buckets in the Google Cloud project | | list_objects | readonly | List objects in a bucket with prefix and pagination | | get_object | readonly | Get object contents as text | | download_object | readonly | Download a single object to a local file (binary-safe) | | download_prefix | readonly | Recursively download a prefix to a local directory (binary-safe) | | head_bucket | readonly | Check if a bucket exists and is accessible | | put_object | readwrite | Upload or update an object from inline string content | | put_object_from_path | readwrite | Upload a single local file by streaming from disk (binary-safe, context-free) | | upload_prefix | readwrite | Recursively upload a local directory tree from disk (binary-safe, context-free) | | copy_object | readwrite | Copy an object within or across buckets | | create_bucket | readwrite | Create a new GCS bucket | | delete_object | delete | Delete an object from a bucket | | delete_bucket | delete | Delete an empty GCS bucket |

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

| Resource | Description | | -------------- | ----------------------------------------------- | | gcs://config | Server configuration and status (for debugging) |

Tool Groups

Control which tools are available via the GCS_ENABLED_TOOLGROUPS environment variable:

| Group | Description | | ----------- | ---------------------------------------------------- | | readonly | Read-only operations (list, get, head) | | readwrite | Non-destructive write operations (put, copy, create) | | delete | Delete operations (delete_object, delete_bucket) |

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

| Mode | Permission the healthcheck needs | Notes | | ------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Single bucket (GCS_BUCKET set) | storage.objects.list on the constrained bucket | Probes list_objects with maxResults: 1. Does not require project-level storage.buckets.list or bucket-metadata storage.buckets.get, so a correctly least-privilege, object-only service account can start. | | Unconstrained (no GCS_BUCKET) | project-level storage.buckets.list | Validates by listing buckets in the project. |

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:

| Tool / group | Permission | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | list_objects (readonly) | storage.objects.list | | get_object, download_object (readonly) | storage.objects.get | | download_prefix (readonly) | storage.objects.list, storage.objects.get | | list_buckets (readonly) | storage.buckets.list | | head_bucket (readonly) | storage.buckets.get | | put_object, put_object_from_path, upload_prefix, copy_object (readwrite) | storage.objects.create, storage.objects.get (these tools read each object's metadata back after writing to return its etag/generation; copy_object additionally reads the copy source) | | create_bucket (readwrite) | storage.buckets.create | | delete_object (delete) | storage.objects.delete | | delete_bucket (delete) | storage.buckets.delete |

For a read-only, single-bucket service account, the roles/storage.objectViewer role on the bucket (or a custom role with storage.objects.list + storage.objects.get) is sufficient — no project-level or bucket-metadata permissions are needed.

Quick Start

Configuration

Environment Variables

| Variable | Required | Description | Default | | ------------------------------ | -------- | ------------------------------------------ | ----------- | | GCS_PROJECT_ID | Yes | Google Cloud project ID | - | | GCS_SERVICE_ACCOUNT_KEY_FILE | No | Path to service account key JSON file | - | | GCS_SERVICE_ACCOUNT_KEY_JSON | No | Service account key JSON contents (inline) | - | | GCS_BUCKET | No | Constrain operations to single bucket | - | | GCS_ENABLED_TOOLGROUPS | No | Comma-separated tool groups | All enabled | | GCS_ENABLED_TOOLS | No | Specific tools to enable | - | | GCS_DISABLED_TOOLS | No | Specific tools to disable | - | | SKIP_HEALTH_CHECKS | No | Skip credential validation | false |

Authentication

The server supports three authentication methods (in order of precedence):

1. Service Account Key File: Set GCS_SERVICE_ACCOUNT_KEY_FILE to the path of a JSON key file
2. Inline Service Account Key: Set GCS_SERVICE_ACCOUNT_KEY_JSON with the JSON contents directly
3. Application Default Credentials (ADC): No additional env vars needed - uses gcloud auth application-default login

Claude Desktop Configuration

If this is your first time using MCP Servers, make sure you have the Claude Desktop application and follow the official MCP setup instructions.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gcs": {
      "command": "npx",
      "args": ["-y", "gcs-google-mcp-server"],
      "env": {
        "GCS_PROJECT_ID": "your-project-id",
        "GCS_SERVICE_ACCOUNT_KEY_FILE": "/path/to/service-account-key.json",
        "GCS_ENABLED_TOOLGROUPS": "readonly"
      }
    }
  }
}

Restart Claude Desktop and you should be ready to go!

Read-Only Mode

For safer exploration, enable only read operations:

{
  "env": {
    "GCS_ENABLED_TOOLGROUPS": "readonly"
  }
}

Using Application Default Credentials

If you have gcloud CLI configured locally:

gcloud auth application-default login

Then configure without key file:

{
  "env": {
    "GCS_PROJECT_ID": "your-project-id"
  }
}

Development

Install Dependencies

npm run install-all

Build

npm run build

Running in Development Mode

npm run dev

Testing

# Run functional tests
npm run test:run

# Run integration tests (full MCP protocol)
npm run test:integration

# Run manual tests (real GCS - requires .env)
npm run test:manual:setup  # First time only
npm run test:manual

# Run all automated tests
npm run test:all

Manual Testing Setup

Create a .env file in the gcs directory:

GCS_PROJECT_ID=your-project-id
GCS_SERVICE_ACCOUNT_KEY_FILE=/path/to/service-account-key.json

Then run:

npm run test:manual

Project Structure

gcs/
├── local/                 # Local server implementation
│   ├── src/
│   │   ├── index.ts      # Main entry point with env validation
│   │   └── index.integration-with-mock.ts
│   └── package.json
├── shared/               # Shared business logic
│   ├── src/
│   │   ├── server.ts     # Server factory with DI
│   │   ├── tools.ts      # Tool registration with grouping
│   │   ├── tools/        # Individual tool implementations
│   │   ├── resources.ts  # Resource implementations
│   │   ├── gcs-client/   # Google Cloud Storage client wrapper
│   │   └── logging.ts
│   └── package.json
├── tests/                # Test suite
│   ├── functional/       # Unit tests with mocks
│   ├── integration/      # MCP protocol tests
│   ├── manual/          # Real API tests
│   └── mocks/           # Mock implementations
└── package.json         # Root workspace config

License

MIT