Google Workspace CLI：一行指令操控你的整个 Google 生态系

Google 有二三十个 Workspace API，每个都要自己搞 SDK、搞认证，光想就累。GWS CLI 把这整个流程变成三行指令：安装、登入、执行。Drive、Gmail、日历、试算表，全部在终端机里用指令操作。还内建 MCP 伺服器，Claude Desktop 可以直接透过它操控你的 Google Workspace。

一、GWS 是什么？为什么你需要它

写过 Google API 自动化脚本的人一定遇过这种事：光一个 Drive API 就要装 SDK、设定认证金钥、写登入验证的流程，搞半天才拿到一个档案列表。

GWS 就是把这整个流程变成三行指令：安装、登入、执行。而且它会自动去读 Google 官方的 API 清单，所以 Google 那边 API 有更新，GWS 这边自动就有新功能，不用等工具本身升版。GitHub 上 6800+ 颗星，Apache 2.0 授权。

二、安装 GWS CLI

GWS 是用 Node.js 写的，直接用 npm 全域安装。-g 就是全域的意思，装完之后在任何目录都能用 GWS 这个指令：

 Bash 
npm install -g @googleworkspace/cli

装完确认一下有没有装成功：

 Bash 
GWS --help

如果有跑出说明画面就代表 OK 了。drive、sheets、gmail、calendar、docs、chat、admin...二十多个 Google 服务，一个工具搞定。

三、认证设定

这边有两种方式。如果不确定选哪个，直接看方式二就好，方式一需要额外装 gcloud。

方式一：用 gcloud 自动设定

如果电脑已经有装 gcloud CLI，直接跑：

 Bash 
GWS auth setup

它会自动帮你建 Google Cloud 专案、开 API、设定好 OAuth 认证。全自动，跟着画面点就好。如果已经有 GCP 专案，可以加 --project 指定。

方式二：手动设定 OAuth（大部分人用这个）

步骤如下：

到 Google Cloud Console，建一个新专案，或用现有的
到「APIs & Services」→「OAuth consent screen」，设定同意画面。Application type 选 External，App name 随便取一个像「GWS-cli」就行
重点 — 在同意画面的 Test users 里面，把你自己的 Google 帐号加进去，然后记得按 Save。这一步漏掉等一下登入会跳「Access blocked」的错误
到「Credentials」→「Create Credentials」→「OAuth client ID」，Application type 选「Desktop app」
建好之后点「Download JSON」下载认证档，放到以下路径：

 Bash 
mkdir -p ~/.config/GWS
# 把下载的 JSON 档复制过去
cp ~/Downloads/client_secret_*.json ~/.config/GWS/client_secret.json

注意：这个 JSON 档一定要先放好，不然下一步登入会直接报 401 错误说找不到认证设定。

然后登入。GWS auth login 会自动启动浏览器跳到 Google 的授权页面：

 Bash 
GWS auth login

确认登入状态：

 Bash 
GWS auth status

看到 credential_source 不是 none 就表示认证成功了。

如果应用还在测试模式，Google 会限制最多只能选 25 个权限范围。可以用 --scopes 指定需要的权限，或者用 --readonly 只要唯读权限：

 Bash 
# 指定特定权限
GWS auth login --scopes https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/gmail.readonly

# 或者只要唯读权限
GWS auth login --readonly

四、Drive 档案管理

GWS 的指令结构是 GWS 加上服务名称，再加上资源跟动作。所以 drive files list 就是「Drive 服务、files 资源、list 动作」。

列出 Drive 里最近的 5 个档案：

 Bash 
GWS drive files list --params '{"pageSize": 5}'

搭配 jq 只显示档案名称：

 Bash 
GWS drive files list --params '{"pageSize": 10}' | jq -r '.files[].name'

搜�的特定档案：

 Bash 
GWS drive files list --params '{"q": "name contains '\''report'\''", "pageSize": 5}'

档案很多需要翻页的话，加 --page-all 自动翻页，--page-limit 限制最多翻几页：

 Bash 
GWS drive files list --params '{"pageSize": 100}' --page-all --page-limit 3

上传档案：

 Bash 
GWS drive files create --json '{"name": "test-upload.txt"}' --upload ./test-upload.txt

五、Gmail 收发信

GWS 里面前面加 + 的都是快捷指令，帮你把常见操作包装好了。+triage 帮你整理未读信件的摘要：

 Bash 
GWS gmail +triage

用原始 API 列出最近的信件：

 Bash 
GWS gmail users messages list --params '{"userId": "me", "maxResults": 5}'

查看单封信的完整内容（把 id 换成实际的信件 ID）：

 Bash 
GWS gmail users messages get --params '{"userId": "me", "id": "你的信件ID贴这里"}'

发信用 +send 快捷指令：

 Bash 
GWS gmail +send --to someone@example.com --subject "测试" --body "这封信是用GWS CLI发的"

六、日历行程与试算表

+agenda 快捷指令会去 Google 日历抓即将到来的行程：

 Bash 
GWS calendar +agenda

新增日历事件：

 Bash 
GWS calendar +insert --summary "团队周会" --start "2026-03-10T10:00:00+08:00" --end "2026-03-10T11:00:00+08:00"

建立新的试算表：

 Bash 
GWS sheets spreadsheets create --json '{"properties": {"title": "专案追踪表"}}'

看到回传的 spreadsheetUrl，直接在浏览器打开就是你刚建的试算表。

七、API 规格查询与模拟执行

不确定某个 API 要带什么参数？不用去翻 Google 的文件，直接在终端机查：

 Bash 
GWS schema drive.files.list

它会直接从 Google 官方拉最新的 API 规格回来，告诉你有哪些参数、什么型态、哪些必填。

--dry-run 是模拟执行，把请求组好但不会真的送出去，让你确认参数都对了再跑：

 Bash 
GWS drive files list --params '{"pageSize": 5}' --dry-run

--format 可以换输出格式。预设是 JSON，还可以切成表格、yaml 或 csv：

 Bash 
GWS drive files list --params '{"pageSize": 5}' --format table

八、跨服务工作流程自动化

GWS 内建的工作流程指令，可以跨服务做自动化。像 +standup-report 会自动抓今天的行程跟待办事项，帮你生一份站会报告。+meeting-prep 帮你准备下一场会议的资讯。+email-to-task 可以把 Gmail 直接转成待办清单。

 Bash 
GWS workflow +standup-report

它会同时去撈日历和待办清单的资料，然后整理成一份摘要。每天早上打一行指令，站会素材就有了。

九、MCP 伺服器：让 Claude Desktop 操控 Google Workspace

GWS 内建 MCP 伺服器。设定好之后，Claude Desktop 就能直接透过它来操作你的 Google Workspace。

启动 MCP 伺服器：

 Bash 
GWS mcp -s drive,gmail,calendar

在 Claude Desktop 里使用的话，编辑设定档：

 路径 
~/Library/Application Support/Claude/claude_desktop_config.json

加入以下设定：

 JSON 
{
  "mcpServers": {
    "google-workspace": {
      "command": "GWS",
      "args": ["mcp", "-s", "drive,gmail,calendar"]
    }
  }
}

存档后重启 Claude Desktop，就可以在对话里直接叫 Claude 帮你操作 Google Workspace 了。比如「帮我列出 Drive 里最近改的 10 个档案」、「帮我看一下今天行程」。

如果想要更多功能，加上 -w 和 -e。-w 把跨服务的工作流程也开放给 AI，-e 开放每个服务额外的快捷指令：

 Bash 
GWS mcp -s drive,gmail,calendar -w -e

十、多帐号切换管理

GWS 支援多帐号切换。登入时加 --account 指定信箱，它会把认证分开存：

 Bash 
GWS auth login --account work@company.com
GWS auth login --account personal@gmail.com

确认当前登入的帐号：

 Bash 
GWS auth list

切换预设帐号：

 Bash 
GWS auth default --account work@company.com

也可以用环境变数临时指定：

 Bash 
GOOGLE_WORKSPACE_CLI_ACCOUNT=work@company.com GWS drive files list --params '{"pageSize": 5}'

十一、常见踩坑与注意事项

问题	原因	解决方式
Access blocked	没有在 OAuth 同意画面的 Test users 里加自己的信箱	回去加上就好
restricted_client 错误	测试模式权限超过 25 个	用 `--scopes` 只选需要的，或送审验证
API 未启用	对应的 Google API 没开	点错误讯息里的启用连结即可

提醒：这个工具目前还没到 1.0 版，功能介面可能会有不相容的更新。如果要在正式环境用的话，版本记得锁好。

十二、总结

功能	指令范例
安装	`npm install -g @googleworkspace/cli`
认证	`GWS auth login`
Drive 档案	`GWS drive files list --params '{"pageSize": 5}'`
Gmail 收发	`GWS gmail +triage` / `GWS gmail +send`
日历行程	`GWS calendar +agenda`
试算表	`GWS sheets spreadsheets create`
API 查询	`GWS schema drive.files.list`
工作流程	`GWS workflow +standup-report`
MCP 伺服器	`GWS mcp -s drive,gmail,calendar`

GWS 就是把 Google 全家桶的 API 包成一个命令列工具。装起来、认证一次，然后 Drive、Gmail、日历、试算表全部用指令操作就好。加上 MCP 伺服器，还能让 AI 工具帮你操控整个 Google Workspace。