Google Workspace MCP

🌐 google-workspace-mcp

一個 MCP 服務器，掌管你所有的 Google 賬號。

面向 Claude Code 的多賬號 Google Workspace MCP 服務器 —— 支持 Gmail、Calendar、Drive 與 Tasks，可並行操作任意數量的 Google 賬號。每一個工具調用都需要傳入一個 account slug，因此單次 Claude 會話即可用一個賬號發送郵件、在另一個賬號的 Drive 中歸檔文件、再在第三個賬號中預訂日程。以 Claude Code 插件形式分發，其自身同時也是一個 marketplace。

✨ 為什麼選擇 google-workspace-mcp

• 🔗 一個服務器，所有賬號。 每次工具調用都傳入一個 account slug（如 work、personal）。服務器會透明地加載並刷新該賬號的 OAuth token —— 無需切換、無需部署多個服務器。
• 🔒 按項目隔離訪問控制。 賬號在運行時配置，絕不寫死在代碼中。每個項目的 .mcp.json 只暴露其所需的賬號子集，因此個人項目甚至看不到你的工作賬號。
• 🪪 使用你自己的 OAuth 客戶端。 你自帶一個（免費的）Google Cloud OAuth 客戶端，因而你完全掌控訪問權限，並獲得完整工具集 —— 包括默認 claude.ai 連接器無法做到的操作，比如刪除草稿。全程不經過任何第三方基礎設施。
• 🗝️ 密鑰永不入庫。 OAuth 客戶端和每賬號的 refresh token 位於 ~/.config/google-workspace-mcp/（權限 0600），絕不與代碼放在一起。
• 🧰 橫跨四類服務共 38 個工具 —— 詳見下方工具目錄。

📖 目錄

• 安裝
• 配置
• 按項目隔離訪問控制
• 工具
• 配置與存儲
• 授權範圍
• 信任與安全
• 倉庫結構
• 開發
• 貢獻
• 許可證

🚀 安裝

/plugin 命令在 Claude Code 內部運行 —— 請在提示符處直接輸入。

# 1) 註冊 marketplace（每臺機器只需一次）
/plugin marketplace add rajool/google-workspace-mcp

# 2) 安裝插件
/plugin install google-workspace-mcp@google-workspace-mcp

安裝完成後你將獲得 /google-workspace-setup 命令，它會引導你完成配置章節中的全部流程 —— 檢查前置依賴、創建 OAuth 客戶端、定義賬號、在正確的瀏覽器中逐個授權，並把服務器接入你的項目。

{
  "extraKnownMarketplaces": {
    "google-workspace-mcp": {
      "source": { "source": "github", "repo": "rajool/google-workspace-mcp" }
    }
  },
  "enabledPlugins": {
    "google-workspace-mcp@google-workspace-mcp": true
  }
}

⚙️ 配置

需要 uv 已在你的 PATH 中（安裝 uv）。/google-workspace-setup 命令會自動完成這些步驟；以下為手動操作路徑。

1. 創建你自己的 Google Cloud OAuth 客戶端

每位用戶自行創建（免費）：

1. 前往 Google Cloud Console，創建一個項目（或選擇一個已有的項目）。

2. APIs & Services → Enabled APIs & services → + Enable APIs —— 啟用 Gmail、Google Calendar、Google Drive 與 Google Tasks 四個 API。

3. APIs & Services → OAuth consent screen —— User type 選擇 External。填寫必填字段。在 Test users 下添加你打算連接的每一個 Google 賬號。（將應用停留在 Testing 狀態即可。）

4. APIs & Services → Credentials → + Create credentials → OAuth client ID → Application type: Desktop app。下載生成的 JSON。

5. 將該 JSON 保存為：

   ~/.config/google-workspace-mcp/credentials.json
   

2. 安裝服務器二進制

這樣項目的 .mcp.json 就能按名稱啟動它：

# 從 GitHub 安裝：
uv tool install git+https://github.com/rajool/google-workspace-mcp

# ……或從本地克隆安裝：
uv tool install .

這會安裝兩個命令：google-workspace-mcp（服務器）和 google-workspace-authorize（OAuth 輔助工具）。

3. 定義你的賬號

給每個賬號起一個簡短的 slug。有兩種方式：

a) 註冊表文件（推薦）—— ~/.config/google-workspace-mcp/accounts.json（模板：）：

{
  "accounts": {
    "work":     { "email": "you@company.com", "name": "Your Name" },
    "personal": { "email": "you@gmail.com",   "name": "Your Name" }
  }
}

name 是發件時顯示在 From: 頭中的展示名（設為 "" 則以裸郵箱地址發送）。

b) 或在每個項目中內聯，通過 GWM_ACCOUNTS 環境變量傳入（參見第 5 步）—— 若不想維護共享註冊表文件，這種方式更方便。

4. 逐個授權賬號

該命令會打印一個 Google 授權 URL —— 在已登錄對應賬號的瀏覽器中打開它，點擊 Allow：

# 賬號已在 accounts.json 中 —— 只需傳 slug：
google-workspace-authorize work

# 或內聯註冊一個全新賬號（會自動寫入 accounts.json）：
google-workspace-authorize personal you@gmail.com "Your Name"

你會依次點過“Google hasn't verified this app”警告（這是你自己的應用）→ Continue → Select all → Continue。Refresh token 會被寫入 ~/.config/google-workspace-mcp/tokens/<slug>.json。

5. 接入項目

在項目根目錄添加 .mcp.json。GWM_ACCOUNTS 決定該項目可以使用哪些賬號：

{
  "mcpServers": {
    "google-workspace": {
      "command": "google-workspace-mcp",
      "env": { "GWM_ACCOUNTS": "work,personal" }
    }
  }
}

• GWM_ACCOUNTS 可以是註冊表中 slug 的逗號分隔列表，也可以是內聯 JSON 映射（{"work":{"email":"…","name":"…"}}）——若跳過了註冊表文件則用後者。
• 省略 GWM_ACCOUNTS 則暴露註冊表中的所有賬號。

重啟 Claude Code（或重連 MCP）使其生效，然後讓 Claude 列出賬號以確認。

🔐 按項目隔離訪問控制

GWM_ACCOUNTS 的意義在於隔離：某項目根本無法以不在其列表中的賬號身份行事 —— 服務器會直接拒絕該 slug。Token 集中存儲（授權一次即可），但每個項目的 .mcp.json 各自選擇所需切片：

🧰 工具

每次調用都需要一個 account slug。accounts_list 會列出已配置的賬號及其 token 是否有效。

📧 Gmail

📅 Calendar

📁 Drive

✅ Tasks

🗂️ 配置與存儲

所有內容都位於 config home 之下 —— $GWM_HOME，其次 $XDG_CONFIG_HOME/google-workspace-mcp，否則 ~/.config/google-workspace-mcp/：

Token 文件以 0600 權限寫入。

🔑 授權範圍

刻意申請了較寬的範圍 —— 這些是你自己的賬號；範圍收窄會導致每次新增工具時都必須重新授權：

• https://mail.google.com/
• https://www.googleapis.com/auth/calendar
• https://www.googleapis.com/auth/drive
• https://www.googleapis.com/auth/tasks

⚠️ 重要提示

新增授權範圍（如 v0.3.0 為 Tasks 所做的那樣）需要為每個賬號重新運行 google-workspace-authorize <slug>。

🛡️ 信任與安全

• 🔒 純本地運行。 服務器僅通過 stdio 與 Claude Code 通信，且只連接 Google 的 API。它唯一開啟過的監聽器是 google-workspace-authorize 期間臨時的 127.0.0.1 重定向，一旦授權落地便立即關閉。
• 🪪 你的客戶端、你的 token。 OAuth 客戶端與 token 只留在你的機器上，位於本倉庫之外。切勿提交 credentials.json 或 tokens/（打包的 已拒絕二者）。
• 🚫 用戶之間零共享。 每位團隊成員運行各自獨立的 OAuth 客戶端並授權各自的賬號。
• 🗝️ 請把配置目錄視為密鑰庫。 Token 授予了對你的郵件/日曆/Drive/Tasks 的寬泛訪問權限 —— ~/.config/google-workspace-mcp/ 值得享受與 ~/.ssh/ 同等的小心對待。
• 一個能發郵件、能共享文件的 MCP 服務器，在啟用前值得審閱 —— 全部表面代碼約 1,300 行 Python，位於 。如需報告安全漏洞，請參閱 SECURITY.md。

📂 倉庫結構

google-workspace-mcp/
├── .claude-plugin/
│   ├── plugin.json                  # 插件清單
│   └── marketplace.json             # 單倉庫 marketplace（source: "./"）
├── commands/
│   └── google-workspace-setup.md    # /google-workspace-setup —— 引導式配置
├── src/google_workspace_mcp/
│   ├── server.py                    # MCP 服務器 —— 全部 38 個工具
│   ├── auth.py                      # token 加載/刷新 + Google 服務構建器
│   ├── accounts.py                  # 運行時賬號註冊表 + GWM_ACCOUNTS 作用域
│   └── authorize.py                 # 獨立的 OAuth 授權流程（CLI）
├── accounts.example.json            # ~/.config/google-workspace-mcp/accounts.json 的模板
├── pyproject.toml                   # uv/hatchling 包 —— 兩個 console scripts
└── .github/workflows/ci.yml         # lint、導入冒煙測試、清單校驗

🛠️ 開發

git clone https://github.com/rajool/google-workspace-mcp
cd google-workspace-mcp
uv sync                                   # 創建 .venv 並鎖定依賴
claude --plugin-dir .                     # 無需安裝即可加載插件

# 質量門禁（CI 運行的檢查相同 —— 見 .github/workflows/ci.yml）
uvx ruff check .                          # lint
uv run python -m py_compile src/google_workspace_mcp/*.py
uv run python -c "from google_workspace_mcp import server"   # 導入冒煙測試
claude plugin validate . --strict         # 校驗插件 + marketplace 清單

任何面向用戶的變更都需要同步提升 、 以及 src/google_workspace_mcp/__init__.py 中的 version，並向 添加一條記錄 —— 已安裝的項目會在執行 /plugin marketplace update 時獲取更新。

🤝 貢獻

歡迎任何形式的貢獻。本倉庫是公開的、通用的、純英文的 —— 不得出現個人郵箱、真實賬號 slug、家目錄路徑或任何密鑰。開發環境搭建與檢查項請參閱 CONTRIBUTING.md，社區行為準則請參閱 CODE_OF_CONDUCT.md。

📄 許可證

MIT © Ali Rajool。與 yar 和 boote 同屬一個工具集家族。