概述
gws 是 Google 官方发布的 Google Workspace 命令行工具，采用 MIT 开源协议，由 googleworkspace 组织在 GitHub 维护。该工具通过动态解析 Google Discovery Service 自动生成 CLI 接口，覆盖 Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin、Tasks、Meet 等全部 Workspace API，并随 Google API 更新自动同步。
核心用法
基础命令
- API 调用:
gws <service> <method> --params '<json>'或--json '<json>' - Schema 查询:
gws schema <resource.method>查看任意接口的参数结构 - 分页流式处理:
--page-all配合管道符实现大数据集处理 - 干运行:
--dry-run预览请求而不实际执行
认证流程（关键前置步骤）
工具要求一次性手动配置 OAuth 凭证，支持三种方式：
- gcloud 集成（推荐）：
gws auth setup自动创建 GCP 项目并启用 API - 手动配置：在 GCP Console 创建 OAuth 2.0 Desktop 应用凭证
- 服务账号：
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE环境变量指向 JSON 密钥
凭证采用 AES-256-GCM 加密存储于系统密钥环。
MCP 原生支持
gws mcp 命令可将任意 Workspace API 暴露为 MCP 工具，支持：
- 服务筛选:
-s drive,gmail,calendar限定暴露的 API 范围 - 紧凑模式:
--tool-mode compact将 200-400 个工具压缩为约 26 个元工具，显著节省上下文窗口
显著优点
1. 官方权威性: 由 Google 组织直接维护，API 覆盖率 100%，自动同步 Discovery Service
2. MCP 原生集成: 无需额外包装，一键启动 MCP 服务器，是 AI 代理集成 Workspace 的首选方案
3. 零样板代码: 结构化 JSON 输出，与 jq 和脚本生态无缝协作
4. 多安装渠道: npm（@googleworkspace/cli）、Cargo、Nix 均支持
5. 安全设计: 凭证加密存储，支持服务账号和 OAuth 2.0 两种认证模式
潜在局限
1. 认证门槛: 必须完成一次性手动 GCP 项目配置，无法即装即用
2. 预发布状态: v1.0 之前版本，API 可能发生破坏性变更
3. 学习曲线: 直接使用 Discovery API 的命名风格，命令较长（如 gws gmail users messages list），需参考 schema 探索
4. 权限范围宽泛: Workspace Admin API 操作影响组织级别，需审慎授权
适用人群
- AI 代理开发者: 需要为 Claude、Cursor、VS Code 等工具提供 Workspace 能力的场景
- DevOps/SRE: 自动化邮件处理、日历调度、报表生成等运维工作流
- 数据工程师: 通过 Sheets/Drive API 构建数据管道
- Google Workspace 管理员: 批量用户、群组、组织架构管理
常规风险
- OAuth 授权范围: 首次授权需确认敏感权限（邮件读取、日历写入等），建议在专用 GCP 项目中配置
- API 配额: 大规模自动化可能触发 Workspace API 速率限制
- 服务账号域级委托: 若用于跨用户数据访问，需额外配置 Google Workspace 管理员授权
- 凭证泄露: 服务账号 JSON 文件需妥善保管，避免提交至版本控制