@pulsemcp/cloud-storage

Cloud Storage MCP Server

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

MCP server for cloud storage operations. Currently supports Google Cloud Storage (GCS) with planned support for AWS S3 in the future.

Highlights

• Full CRUD operations for cloud storage files (save, get, search, delete)
• Files exposed as MCP Resources for easy browsing
• Support for both inline content and local file references (preserves context window for large/binary files)
• Flexible authentication (individual env vars, key file, or default credentials)
• Optional root directory scoping within a bucket
• Tool grouping for permission-based access control

Capabilities

Tools

Tool	Group	Description
save_file	write, admin	Save a file to cloud storage (inline content or local file)
get_file	readonly+	Get a file from cloud storage (inline or save to local file)
search_files	readonly+	Search/list files with prefix filtering and pagination
delete_file	admin	Delete a file from cloud storage

Resources

Files in the cloud storage bucket are automatically exposed as MCP resources:

Resource	Description
cloud-storage://config	Server configuration and status (for debugging)
cloud-storage://file/{path}	Individual files in the bucket

Tool Groups

Control which tools are available via the ENABLED_TOOLGROUPS environment variable:

Group	Description
readonly	Read-only operations (get_file, search_files)
write	Write operations (includes readonly + save_file)
admin	All operations (includes write + delete_file)

Examples:

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

Configuration

Environment Variables

Variable	Required	Description	Default
GCS_BUCKET	Yes	Google Cloud Storage bucket name	-
GCS_ROOT_DIRECTORY	No	Optional root directory prefix in the bucket	Bucket root
GCS_PROJECT_ID	No	Google Cloud project ID	From default creds
GCS_KEY_FILE	No	Path to service account JSON key file	Uses default creds
GCS_CLIENT_EMAIL	No	Service account email (alternative to key file)	Uses key file
GCS_PRIVATE_KEY	No	Service account private key (use with CLIENT_EMAIL)	Uses key file
ENABLED_TOOLGROUPS	No	Comma-separated tool groups to enable	All enabled
SKIP_HEALTH_CHECKS	No	Skip bucket connectivity check at startup	false

Authentication

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

• Individual Credential Environment Variables (recommended for secrets managers):

  • Set GCS_CLIENT_EMAIL, GCS_PRIVATE_KEY, and GCS_PROJECT_ID
  • Useful when you don't want to store a JSON key file on disk
  • The private key should be in PEM format (can include literal \n for newlines)

• Service Account Key File:

  • Set GCS_KEY_FILE to the path of your service account JSON key file
  • Optionally set GCS_PROJECT_ID (often included in the key file)

• Application Default Credentials (ADC):

  • If no credentials are provided, uses Google Cloud's Application Default Credentials
  • Works automatically on GCE, Cloud Run, or after running gcloud auth application-default login

Claude Desktop Configuration

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

Using key file:

{
  "mcpServers": {
    "cloud-storage": {
      "command": "npx",
      "args": ["-y", "@pulsemcp/cloud-storage"],
      "env": {
        "GCS_BUCKET": "my-bucket-name",
        "GCS_KEY_FILE": "/path/to/service-account-key.json",
        "GCS_ROOT_DIRECTORY": "optional/prefix"
      }
    }
  }
}

Using individual credential env vars:

{
  "mcpServers": {
    "cloud-storage": {
      "command": "npx",
      "args": ["-y", "@pulsemcp/cloud-storage"],
      "env": {
        "GCS_BUCKET": "my-bucket-name",
        "GCS_PROJECT_ID": "my-project-id",
        "GCS_CLIENT_EMAIL": "[e-mail]",
        "GCS_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
      }
    }
  }
}

Usage Examples

Save a File (inline content)

Use the save_file tool to save a configuration file:
- path: "config/settings.json"
- content: "{\"debug\": true, \"version\": \"1.0\"}"
- content_type: "application/json"

Save a File (from local file)

Use the save_file tool to upload an image:
- path: "images/logo.png"
- local_file_path: "/tmp/logo.png"

Get a File

Use the get_file tool to retrieve a file:
- path: "config/settings.json"

Get a Binary File (preserve context window)

Use the get_file tool to download an image:
- path: "images/logo.png"
- local_file_path: "/tmp/downloaded-logo.png"

Search Files

Use the search_files tool to list files:
- prefix: "documents/"
- limit: 50

Delete a File

Use the delete_file tool:
- path: "temp/old-file.txt"

Future Work

• AWS S3 Support: Add S3StorageClient implementation with similar interface
• Azure Blob Storage: Potential future support for Azure Blob Storage
• File Versioning: Support for bucket versioning features
• Signed URLs: Generate temporary signed URLs for file sharing

Development

Building

npm run build

Testing

# Run functional tests
npm test

# Run integration tests
npm run test:integration

# Run manual tests (requires GCS credentials)
npm run test:manual

License

MIT