Google Workspace MCP

為什麼要用

核心特性

單一伺服器整合 12 項服務：Gmail、Drive、Calendar、Docs、Sheets、Slides、Forms、Tasks、Contacts、Chat、Apps Script、Custom Search
分層工具集（core／extended／complete）讓工具清單保持簡潔
OAuth 2.0 + 2.1，支援多使用者 bearer token 模式，適用於託管部署
Docker／Kubernetes 無狀態模式
加密本機 token 快取；可選 GCS 憑證儲存

即時演示

實際使用效果

google-workspace-mcp.replay ▶ 就緒

0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示，然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "google-workspace-mcp",
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列，而非映射。

~/.config/zed/settings.json

{
  "context_servers": {
    "google-workspace-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "workspace-mcp",
          "--tool-tier",
          "core"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add google-workspace-mcp -- uvx workspace-mcp --tool-tier core

一行命令搞定。用 claude mcp list 驗證，claude mcp remove 移除。

使用場景

實戰用法： Google Workspace MCP

讓 Claude 協助你將 Gmail 收件匣清零

👤 有 200 封以上未讀郵件的任何人 ⏱ ~25 min beginner

何時使用： 週一早上，收件匣塞滿郵件時。

前置條件

Google Cloud OAuth 用戶端 — 在 console.cloud.google.com 建立 OAuth 2.0 憑證，下載 client_secret.json
伺服器已安裝 — uvx workspace-mcp --tool-tier core（首次呼叫時會開啟瀏覽器進行 OAuth 授權）

步驟

收件匣分類

Use google-workspace-mcp. List unread mail from the last 7 days. Bucket into: action-required, FYI, newsletters, automated.✓ 已複製

→ 各類別數量及主旨範例
自動封存低價值類別

Archive everything in newsletters + automated. Don't touch action-required.✓ 已複製

→ 已封存 N 封，「待處理」類別未受影響
起草回覆

For each action-required email, draft a 2-line reply in my voice. Save as drafts, don't send.✓ 已複製

→ 草稿已顯示在 Gmail 中；由你調整後再發送

結果： 收件匣縮減至 20 封以下，回覆已起草但尚未發送——最終審核仍由你掌控。

注意事項

授予了完整 Gmail 範圍，事後後悔 — 使用 --tool-tier core——除非主動升級至 extended，否則不會有 send_email 工具

搭配使用： filesystem

從 Calendar 與 Docs 活動自動生成每週工作報告

👤 需要撰寫週報的工程師與主管 ⏱ ~10 min beginner

何時使用： 週五下午，忘了這週做了什麼事。

步驟

拉取行事曆

Use google-workspace-mcp. List meetings I attended Mon–Fri this week (skip declined). For each, give 1-line context.✓ 已複製

→ 依時間排序的會議清單，含各會議簡要說明
拉取文件活動

List Drive docs I edited or commented on this week. Group by project.✓ 已複製

→ 依專案分組的文件清單，含編輯／留言次數
起草週報

Combine into a 6-bullet weekly update — what I shipped, what's blocked, what's next.✓ 已複製

→ 可直接貼到 Slack／Email 的草稿

結果： 3 分鐘完成原本需要 30 分鐘的週報，且內容有真實文件佐證。

注意事項

行事曆塞滿重複的一對一會議，汙染報告 — 依活動標題或出席人數篩選——要求 Claude 預設略過重複的一對一會議

從雜亂的 Sheets 擷取結構化資料並回寫結果

👤 營運、財務及每天與試算表為伍的人 ⏱ ~20 min intermediate

何時使用： 試算表中有 1000 列自由文字描述，需要分類整理。

步驟

讀取範圍

Use google-workspace-mcp. Read column B from Sheet 'Q4 expenses' — 1000 rows of vendor descriptions.✓ 已複製

→ 資料列已載入；顯示樣本
分類

Categorize each row into: SaaS, hardware, travel, services, other. Show distribution first.✓ 已複製

→ 分佈表格；抽樣範例供核對
回寫

Write categories into column F. Add a header. Don't touch other columns.✓ 已複製

→ 工作表已更新；手動抽查幾個儲存格確認

結果： 分類結果已寫入試算表，對話紀錄作為稽核軌跡。

注意事項

Claude 覆寫了你在乎的欄位 — 明確指定目標欄位；大量寫入前先驗證幾個儲存格

從行事曆邀請自動生成會議準備文件

👤 行程滿檔的任何人 ⏱ ~15 min intermediate

何時使用： 明天有 5 個會議，對每場都毫無概念。

步驟

掃描明日行程

Use google-workspace-mcp. List tomorrow's meetings with attendees and any attached docs.✓ 已複製

→ 每場會議的出席者及附件文件清單
生成準備簡報

For each, create a Doc 'Prep — <meeting title>' summarizing attached docs + suggesting 3 questions to ask.✓ 已複製

→ N 份文件已建立於「/Meeting prep/」資料夾

結果： 帶著準備走進每場會議，而非毫無頭緒。

注意事項

外部出席者看不到你的準備文件，但標題可能洩露意圖 — 使用私人準備資料夾；標題用「Prep — <主題>」而非「<敏感交易名稱>」

組合

與其他 MCP 搭配，撬動十倍槓桿

google-workspace-mcp + filesystem

將 Drive 文件同步至本機，進行離線編輯或 git 版本追蹤

Pull all docs in /weekly-updates/ from Drive into ./drive-mirror/ as markdown.✓ 已複製

google-workspace-mcp + github

在 GitHub 與 Google Doc 之間同步發布說明

Take the latest GitHub release notes and append them to the 'Release log' Google Doc.✓ 已複製

工具

此 MCP 暴露的能力

工具	輸入參數	何時呼叫	成本
search_gmail	query: str (Gmail 搜尋語法), max_results?	尋找符合自然語言條件的郵件	1 次 Gmail API 呼叫
send_email	to, subject, body, cc?, bcc?	僅限 extended／complete 層——永遠不要在未確認的情況下自動發送	1 次 API 呼叫
list_calendar_events	calendar_id, time_min, time_max	拉取指定日期範圍的活動	1 次 Calendar API 呼叫
read_sheet_range	spreadsheet_id, range（A1 表示法）	從試算表讀取儲存格資料	1 次 Sheets API 呼叫
write_sheet_values	spreadsheet_id, range, values[][]	將運算結果更新至試算表範圍	1 次 API 呼叫
create_doc	title, content（markdown）	從對話輸出生成新文件	1 次 Docs API 呼叫
search_drive	query, mime_type?	依名稱或內容尋找檔案	1 次 Drive API 呼叫

成本與限制

運行它的成本

API 配額: Gmail：250 配額單位／使用者／秒；Calendar：500 請求／100 秒；Sheets：300 請求／分鐘／使用者
每次呼叫 Token 數: 每次呼叫 200–4000 token（視完整郵件內文或僅讀取元數據而定）
費用: 個人 Google 帳戶免費；Workspace 組織可能有管理員限制
提示: 除非確實需要 Forms／Slides／Apps Script，否則使用 --tool-tier core——工具越少，系統提示越精簡

安全

權限、密鑰、影響範圍

最小權限： gmail.readonly calendar.readonly drive.readonly

憑證儲存： 預設為加密本機 token 快取；託管環境可選 GCS

資料出站： 直接連至 googleapis.com——無第三方中轉

切勿授予： gmail.send（在了解自動發送風險之前） drive（全範圍讀寫）

同時支援 OAuth 2.0 + 2.1；除非有機密用戶端設定，否則選用 PKCE 公開用戶端

故障排查

常見錯誤與修復

OAuth 回呼失敗／瀏覽器未開啟

將 OAUTH_REDIRECT_PORT 設為可用埠後重新執行；在無頭伺服器上使用 device-flow 模式

驗證： lsof -i :8080 確認埠口空閒

403 insufficient_permissions

以缺少的範圍重新授權；確認 Google Cloud Console 中 OAuth 用戶端已允許該範圍

驗證： 在 oauth2.googleapis.com/tokeninfo 解碼 token 以查看已授予的範圍

Workspace 管理員封鎖了 OAuth 用戶端

請管理員將你的用戶端 ID 加入信任應用程式清單，或使用個人 Google 帳戶測試

大量操作超出配額

加入退避邏輯；伺服器會遵守 Retry-After 標頭，但批次迴圈仍可能觸發每秒限制

驗證： 監控日誌中的 HTTP 429

替代方案