gcs-browser-mcp

Read-only MCP server for browsing and reading files from Google Cloud Storage. Use with Claude Desktop or any MCP client.

Setup

1. Get credentials

You need a GCP service account JSON key with roles/storage.objectViewer on the buckets you want to access.

2. Install

npm install gcs-browser-mcp

Or clone and build from source:

npm install
npm run build

3. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gcs-browser": {
      "command": "node",
      "args": ["/path/to/node_modules/gcs-browser-mcp/dist/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json",
        "GCS_ALLOWED_BUCKETS": "my-bucket-1,my-bucket-2"
      }
    }
  }
}

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | GOOGLE_APPLICATION_CREDENTIALS | Yes | Path to GCP service account JSON key file | | GCS_ALLOWED_BUCKETS | No | Comma-separated list of allowed bucket names. If unset, all buckets the SA can access are available |

Tools

list_buckets

List available GCS buckets. If GCS_ALLOWED_BUCKETS is set, only those are shown. Otherwise lists all buckets the service account can see.

list_files

Browse files in a bucket with optional filters:

• prefix — path prefix for directory-style navigation
• filename_contains — substring match on filenames
• max_results — limit results (default 100, max 500)

read_file

Download and return file contents with format-aware parsing:

• JSON — parsed and pretty-printed
• JSONL/JL — paginated with max_lines and offset_lines
• Text — returned raw (truncated at 50KB)

Security

• Read-only — no write, delete, or modify operations
• Bucket allowlist — optionally restrict access via GCS_ALLOWED_BUCKETS
• Path traversal prevention — ../ sequences are stripped and rejected
• File size limit — files over 10MB are rejected
• Audit logging — all tool invocations logged to stderr with timestamps
• No credentials in code — uses GOOGLE_APPLICATION_CREDENTIALS env var only

License

MIT