Claude Code 操作 Gmail 首選 googleworkspace-cli 完整指南

AI
, , , ,
1

比較 gws CLI 與 Gmail-MCP-Server，提供安裝、架構、Agent 技能範例與安全最佳實務，適合 Claude Code、Codex 開發者。

核心結論

若目標是讓 Claude Code 或 Codex 在終端機底層可靠、自主地操作 Gmail，Google Workspace 官方 GitHub 組織維護的 googleworkspace/cli (簡稱 gws) 是目前最佳選擇。它擁有約 28.4k GitHub Stars、主動維護、支援完整 Gmail API 面、輸出結構化 JSON、並內建可安裝的 gws-gmail Agent Skill，完全符合 AI Agent「呼叫已驗證 CLI 工具」的運作模式。

獨立專案 Gmail-MCP-Server (約 778 stars) 仍適合 Claude Desktop 或強制走 MCP tool calling 的工作流，但對終端機原生 Agent 自動化而言，gws 的擴展性（可自然延伸至 Calendar、Drive、Sheets）與維護可信度明顯更高。

專案快速比較

專案 形式 維護方 Stars 適用場景
googleworkspace/cli (gws) CLI + Agent Skills Google Workspace 官方組織 ~28.4k Claude Code、Codex、終端機原生 Agent
Gmail-MCP-Server MCP Server 個人開發者 (GongRzhe) ~778 Claude Desktop、MCP-only client

為什麼選 gws？

  1. 動態 API 面：透過 Google Discovery Service 動態建立指令，Gmail API 新增端點即自動獲得對應 CLI 指令。
  2. 高階 Gmail 命令：內建 +send、+reply、+reply-all、+forward、+triage、+watch（NDJSON 串流新信事件，適合常駐 Agent）。
  3. Agent Skill 就緒：官方提供 gws-gmail Skill，Claude Code / Codex 可直接載入並呼叫，無需自行組裝 MIME 或 thread 操作。
  4. 結構化 JSON 輸出：成功與錯誤結果皆為結構化 JSON，便於 Agent 判斷下一步。
  5. 憑證留在本機：OAuth 2.0 憑證存於 OS keychain / 加密設定，Agent 僅執行 gws 指令，攻擊面較小。

建議架構

Claude Code / Codex
        |
        |  Skill instructions + shell execution
        v
   gws CLI + gws-gmail Skill
        |
        |  OAuth 2.0 (最小 Gmail scopes)
        v
   Gmail API

最短安裝流程

# 1. 安裝 CLI (二選一)
brew install googleworkspace-cli
# 或
npm install -g @googleworkspace/cli

# 2. 初始化 Google Cloud OAuth 並登入 (建議最小 scope)
gws auth setup
gws auth login -s gmail

# 3. 安裝 Gmail Agent Skill
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail

注意：官方 README 建議在未驗證的 OAuth app 使用最小服務集合 (如 -s gmail 或 -s gmail,drive)，避免預設 scope 超過 testing-mode 同意授權限制。

Agent 可執行指令範例

# 收件匣未讀摘要
gws gmail +triage

# 直接寄出郵件
gws gmail +send \
  --to [email protected] \
  --subject "Proposal follow-up" \
  --body "Hi, here is the requested update." 

# 先建立草稿，不直接寄送 (推薦安全做法)
gws gmail +send \
  --to [email protected] \
  --subject "Draft: Campaign update" \
  --body "..." \
  --draft

# 查詢 Gmail 原生 API 指令與 schema
gws gmail --help
gws schema gmail.users.messages.list

gws 同時支援 Gmail API 原生 resources/methods（列出、取得、修改、管理訊息），高階命令則降低 Agent 組裝 MIME 與 thread 的複雜度。

何時保留 Gmail-MCP-Server？

  • 使用介面為 Claude Desktop
  • 工作流嚴格要求 MCP tool calling
  • 需要附件收發/下載、信件搜尋、Label/Filter CRUD、批次修改/刪除等完整 MCP tool schema

此時 Gmail-MCP-Server 仍是 Gmail 專用 MCP 的好選擇，OAuth token 預設存於 ~/.gmail-mcp/credentials.json。

權限與安全最佳實務

  1. 預設拒絕高風險自動授權：不要一開始給予寄送、永久刪除、修改 Filter 的完全自動權限。
  2. 寄信採 Draft-first 流程：Agent 對外寄信先建立 draft，使用者明確確認後才執行寄送。
  3. 刪信、轉寄、建立永久 Filter 設為需確認的高風險動作。
  4. 啟用 Prompt Injection 防護：gws 支援透過 Google Cloud Model Armor 對 Gmail API 回應進行 sanitation，讀取外部來信再採取行動的場景建議加入 --sanitize 參數。

結語

對於 Claude Code / Codex 終端機原生 Agent 自動化操作 Gmail 的需求，googleworkspace/cli + gws-gmail Skill 是目前生態系中最完整、維護最活躍、擴展性最佳的方案。它不僅解決 Gmail 操作，更為未來整合 Calendar、Drive、Sheets、Docs 等 Workspace 服務奠定統一 CLI 基礎，避免為每項服務尋找獨立 MCP repo。

先從最小 scope 開始、採 Draft-first 寄信流程、啟用輸入 sanitation，即可在安全可控前提下釋放 Agent 的 Gmail 自動化能力。