gcs

GCS MCP 服务

用于执行 Google Cloud Storage 操作的 MCP 服务，提供细粒度的工具访问控制。支持对 GCS 存储桶和对象执行读写操作，并可配置工具组以管理安全性和权限。

亮点

• 全面的 GCS 存储桶和对象管理（列出、获取、上传、复制、删除）
• 通过工具组实现细粒度访问控制（readonly、readwrite、delete）
• 通过环境变量启用或禁用单个工具
• 多种身份验证方式（服务账号密钥文件、内联 JSON、ADC）
• GCS 凭据验证与运行状况检查
• 单存储桶约束模式
• 使用 TypeScript 并启用严格类型检查
• 全面的测试（功能测试、集成测试、手动测试）

功能

工具

工具	分组	说明
list_buckets	readonly	列出 Google Cloud 项目中的所有 GCS 存储桶
list_objects	readonly	使用前缀和分页列出存储桶中的对象
get_object	readonly	获取对象内容并以文本形式返回
download_object	readonly	将单个对象下载到本地文件（安全处理二进制数据）
download_prefix	readonly	将某个前缀下的对象递归下载到本地目录（安全处理二进制数据）
head_bucket	readonly	检查存储桶是否存在且可访问
put_object	readwrite	根据内联字符串内容上传或更新对象
put_object_from_path	readwrite	通过从磁盘流式读取，上传单个本地文件（安全处理二进制数据，无上下文限制）
upload_prefix	readwrite	从磁盘递归上传本地目录树（安全处理二进制数据，无上下文限制）
copy_object	readwrite	在同一存储桶内或跨存储桶复制对象
create_bucket	readwrite	创建新的 GCS 存储桶
delete_object	delete	删除存储桶中的对象
delete_bucket	delete	删除空的 GCS 存储桶

下载到本地磁盘

get_object 会将对象内容以内联 UTF-8 文本形式返回，这会导致二进制数据丢失，而且不适合处理大文件或一次处理多个文件。要在本地整理数据，请改用下载工具——这两个工具都会将原始字节流式写入磁盘，且属于 readonly 工具组：

• download_object — 将单个对象下载到本地文件路径。默认下载到操作系统临时目录下的唯一文件。

• download_prefix — 将某个前缀下的所有对象递归下载到本地目录，并将键路径结构保留为子目录。该工具会分页获取完整列表，跳过目录占位对象（键以 / 结尾），收集各对象的错误但不会中止批处理，并返回清单：

  {
    "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": []
  }
  

  内联 files 列表的条目数有上限（maxInlineEntries，默认为 100），但 objectCount 和 totalBytes 始终反映完整下载内容。省略 destinationDir 时，默认使用操作系统临时目录下的唯一文件夹。

从本地磁盘上传

put_object 将对象内容作为字符串参数内联传入，因此每个字节都会经过模型上下文，二进制数据还必须使用 base64 编码——这不适用于大文件或批量上传。若要上传文件或文件夹，而不消耗上下文，请改用本地路径上传工具。这两个工具都会直接从磁盘向 GCS 端流式传输原始字节，且只返回元数据。它们属于 readwrite 工具组，因此只读部署不会启用它们。

• put_object_from_path — 通过从文件系统路径流式传输，上传单个本地文件。系统会根据文件扩展名自动检测内容类型（可通过 contentType 覆盖）。二进制文件（图像、归档文件）无需 base64 编码即可上传。返回 { bucket, key, sourcePath, size, etag, generation }。

• upload_prefix — 递归上传本地目录下的所有文件，并将目录结构保留为目标前缀下的键路径。会跟随指向文件的符号链接并上传文件（跳过指向目录的链接以避免循环）；每个文件的失败都会被收集，不会中止批次，并返回清单：

  {
    "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": []
  }
  

  内联的 files 列表有上限（maxInlineEntries，默认值为 100），但 objectCount 和 totalBytes 始终反映完整上传内容。省略 destPrefix 时，文件会上传到存储桶根目录。

资源

资源	描述
gcs://config	服务配置和状态（用于调试）

工具组

通过 GCS_ENABLED_TOOLGROUPS 环境变量控制可用工具：

组	描述
readonly	只读操作（list、get、head）
readwrite	非破坏性写入操作（put、copy、create）
delete	删除操作（delete_object、delete_bucket）

示例：

• GCS_ENABLED_TOOLGROUPS="readonly" - 仅启用读取操作
• GCS_ENABLED_TOOLGROUPS="readonly,readwrite" - 启用读写操作，不启用删除操作
• GCS_ENABLED_TOOLGROUPS="readonly,readwrite,delete" - 启用所有操作
• 未设置 - 启用所有工具（默认）

单独控制工具

对特定工具进行细粒度控制：

• GCS_ENABLED_TOOLS="list_buckets,get_object" - 仅启用这些工具
• GCS_DISABLED_TOOLS="delete_bucket,delete_object" - 禁用这些工具

单存储桶模式

使用 GCS_BUCKET 将所有操作限制在特定存储桶内：

GCS_BUCKET="my-bucket"

设置后：

• 所有对象操作都会自动限定在此存储桶内
• 存储桶级工具（list_buckets、create_bucket、delete_bucket、head_bucket）会被隐藏
• bucket 参数会自动注入，并从工具输入中隐藏
• 对于 copy_object，源和目标都会被限制在指定存储桶内

这样，你就可以授予服务账号最低限度的权限，使其仅拥有一个存储桶的对象级访问权限，而无需项目级的存储桶列表权限。启动时的健康检查也遵循此限制：设置 GCS_BUCKET 后，系统会使用限定于对象范围的探测（针对该存储桶的 storage.objects.list）验证凭据，且不会调用项目级存储桶列表接口或探测存储桶元数据。有关各模式所需的确切权限，请参阅所需的 IAM 权限。

所需的 IAM 权限

所需的最低 IAM 权限取决于服务是否被限制在单个存储桶（GCS_BUCKET）内，以及启用了哪些工具组。启动时的健康检查会在这些限制范围内验证凭据——根据你的模式，不会要求拥有下表未列出的任何权限。

启动健康检查

模式	健康检查所需权限	说明
单个存储桶（已设置 GCS_BUCKET）	对受限存储桶拥有 storage.objects.list 权限	使用 maxResults: 1 对 list_objects 进行探测。不需要项目级 storage.buckets.list 或存储桶元数据权限 storage.buckets.get，因此，权限遵循最小化原则且仅限对象操作的服务账号也可以启动。
不受限（未设置 GCS_BUCKET）	项目级 storage.buckets.list	通过列出项目中的存储桶进行验证。

设置 SKIP_HEALTH_CHECKS=true 可完全跳过启动验证（禁用所有凭据检查，不推荐）。

各工具的权限

除了健康检查之外，每个工具在运行时都需要相应的 GCS 权限。仅授予启用的工具组所需的权限：

工具 / 组	权限
list_objects（只读）	storage.objects.list
get_object、download_object（只读）	storage.objects.get
download_prefix（只读）	storage.objects.list、storage.objects.get
list_buckets（只读）	storage.buckets.list
head_bucket（只读）	storage.buckets.get
put_object、put_object_from_path、upload_prefix、copy_object（读写）	storage.objects.create、storage.objects.get（这些工具在写入后会读取每个对象的元数据，以返回其 etag/generation；copy_object 还会读取复制源）
create_bucket（读写）	storage.buckets.create
delete_object（删除）	storage.objects.delete
delete_bucket（删除）	storage.buckets.delete

对于只读的单存储桶服务账号，在存储桶上授予 roles/storage.objectViewer 角色（或授予包含 storage.objects.list 和 storage.objects.get 的自定义角色）即可，无需项目级或存储桶元数据权限。

快速开始

配置

环境变量

变量	必需	描述	默认值
GCS_PROJECT_ID	是	Google Cloud 项目 ID	-
GCS_SERVICE_ACCOUNT_KEY_FILE	否	服务账号密钥 JSON 文件的路径	-
GCS_SERVICE_ACCOUNT_KEY_JSON	否	服务账号密钥 JSON 内容（内联）	-
GCS_BUCKET	否	将操作限制在单个存储桶内	-
GCS_ENABLED_TOOLGROUPS	否	以逗号分隔的工具组	全部启用
GCS_ENABLED_TOOLS	否	要启用的特定工具	-
GCS_DISABLED_TOOLS	否	要禁用的特定工具	-
SKIP_HEALTH_CHECKS	否	跳过凭据验证	false

身份验证

服务支持三种身份验证方式（按优先级排序）：

1. 服务账号密钥文件：将 GCS_SERVICE_ACCOUNT_KEY_FILE 设置为 JSON 密钥文件的路径
2. 内联服务账号密钥：将 GCS_SERVICE_ACCOUNT_KEY_JSON 设置为 JSON 内容
3. 应用默认凭据（ADC）：无需设置其他环境变量，使用 gcloud auth application-default login

Claude Desktop 配置

如果这是你首次使用 MCP 服务，请确保已安装 Claude Desktop 应用，并按照 官方 MCP 设置说明进行配置。

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"
      }
    }
  }
}

重启 Claude Desktop，即可开始使用！

只读模式

如需更安全地进行探索，请仅启用读取操作：

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

使用应用默认凭据

如果你已在本地配置 gcloud CLI：

gcloud auth application-default login

然后在不使用密钥文件的情况下进行配置：

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

开发

安装依赖项

npm run install-all

构建

npm run build

在开发模式下运行

npm run dev

测试

# 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

手动测试设置

在 gcs 目录中创建 .env 文件：

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

然后运行：

npm run test:manual

项目结构

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

许可证

MIT