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 同属一个工具集家族。