google-workspace-mcp

多账户、令牌高效的 MCP，支持 Gmail + Calendar + Drive + Docs + Sheets。 之所以构建它，是因为官方的 Claude 连接器只支持一个账户，并且默认返回完整的消息/文件正文。

为什么存在

• 多账户：OAuth 多个邮箱（工作 + 个人 + 联合创始人）。每个工具都接受一个 account 邮箱；别名通过 Send-As 身份处理。

• 令牌高效：搜索/列表返回紧凑的形状（邮件为 {id, from, subject, snippet, ...}，Drive 为 {id, name, mime, modified, size, ...}）。正文和文件内容为可选。

• 基于密钥环：刷新令牌存储在操作系统的凭据存储中——macOS 上的 Keychain、Windows 上的 Credential Manager、Linux 上的 Secret Service——而不是明文文件。保险库中没有令牌，任何仓库中也没有令牌。

• macOS、Windows 和 Linux：每个平台一个安装程序，同一个连接器。

Related MCP server: google-workspace-mcp

工具（v2，63 个工具）

账户管理（3）

• gws_account_add — 浏览器 OAuth 流程，添加一个新的授权邮箱

• gws_account_list — 列出授权账户 + 默认账户

• gws_account_remove — 移除本地凭据（不撤销 Google 端的授权）

Gmail（12）

• gmail_search — 使用 Gmail 操作符搜索。紧凑响应。

• gmail_read — 读取一条消息或完整线程。正文可选。

• gmail_send — 发送邮件，可选 from_alias 用于 Send-As 身份

• gmail_draft — 创建草稿

• gmail_reply — 回复（保留线程 + 标头），可选 reply_all

• gmail_labels_list — 列出所有标签

• gmail_label_apply — 批量添加/移除标签

• gmail_archive — 批量归档（移除 INBOX）

• gmail_trash — 批量移至回收站

• gmail_sendas_list — 列出此邮箱上的 Send-As 身份

• gmail_attachments_list — 列出消息的附件（文件名、MIME 类型、大小）

• gmail_attachment_save — 将单个附件下载到本地文件，返回路径以供直接读取

Calendar（7）

• cal_list_calendars — 列出所有日历

• cal_list_events — 列出即将发生的事件（默认紧凑，verbose=True 获取完整信息）

• cal_create_event — 创建事件，可选 Google Meet 链接

• cal_update_event — 部分更新字段

• cal_delete_event — 删除

• cal_freebusy — 检查忙碌时段以进行调度

• cal_respond — 接受/拒绝/暂定

Drive（18）

• drive_search — 自由文本或原始 Drive q 语法。仅元数据响应。

• drive_read_file — 默认元数据；include_content=True 获取正文

• drive_list_folder — 文件夹的直接子项（'root' 表示 My Drive）

• drive_create_folder — 在可选父目录下创建文件夹

• drive_upload — 上传本地文件，可选 convert_to_google

• drive_move — 更改父文件夹

• drive_rename — 重命名文件或文件夹

• drive_share — 通过电子邮件授予读者/评论者/写者等访问权限

• drive_trash — 软删除（可恢复）

• drive_untrash — 从回收站恢复

• drive_permission_list — 列出有权访问文件的所有人

• drive_permission_update — 更改被授权者的角色

• drive_permission_delete — 撤销权限

• drive_shared_drives_list — 列出此账户访问的共享云端硬盘

• drive_comments_list — 列出任何 Drive 文件（文档/表格/幻灯片/上传）上的评论

• drive_comment_add — 添加评论，可选锚点

• drive_comment_reply — 回复评论

• drive_comment_resolve — 将评论标记为已解决

Docs（9）

• docs_create — 新建文档，可选初始正文和父文件夹

• docs_read — 默认纯文本；structured=True 获取完整 Docs API 树

• docs_append — 在正文末尾追加文本

• docs_insert_at — 在特定索引处插入文本

• docs_replace_text — 查找并替换，返回替换次数

• docs_export — 导出为 markdown / pdf / docx / rtf / plain

• docs_suggestions_list — 列出待处理的跟踪更改建议

• docs_suggestions_accept_all — 接受所有建议（重写文档）

• docs_suggestions_reject_all — 拒绝所有建议（重写文档）

Sheets（14）

• sheets_create — 新建工作簿，可选父文件夹

• sheets_list_sheets — 列出带有行/列维度的标签页

• sheets_add_sheet — 向现有工作簿添加新标签页

• sheets_read_range — 读取 A1 范围。FORMULA / UNFORMATTED_VALUE 选项。

• sheets_write_range — 覆盖范围。USER_ENTERED 解析公式。

• sheets_append — 在现有数据下方追加行

• sheets_clear_range — 清除值（保留格式）

• sheets_batch_read — 一次 API 调用中多范围读取

• sheets_batch_write — 一次 API 调用中多范围写入

• sheets_named_ranges_list — 列出工作簿中的命名范围

• sheets_named_range_add — 创建命名范围

• sheets_named_range_delete — 删除命名范围

• sheets_conditional_format_add — 添加条件格式规则

• sheets_data_validation_add — 设置下拉列表 / 数字 / 电子邮件 / URL 验证

安装

最快路径——一个脚本，无需手动接线。

macOS 和 Linux：

git clone https://github.com/adelaidasofia/google-workspace-mcp.git
bash google-workspace-mcp/install.sh

Windows（PowerShell）：

git clone https://github.com/adelaidasofia/google-workspace-mcp.git
powershell -ExecutionPolicy Bypass -File .\google-workspace-mcp\install.ps1

安装程序会创建隔离的 venv，安装依赖项，获取你的 Google OAuth 客户端（交互式或通过环境中的 GWS_CLIENT_ID / GWS_CLIENT_SECRET），并将服务器注册到 Claude Code。可以安全地重新运行。你仍然需要先有一个 Google OAuth 客户端——请参阅 SETUP.md 了解约 45 分钟的一次性 GCP 设置。然后从 Claude Code 运行 gws_account_add 来授权你的第一个邮箱。

两者都需要 Python 3.10 或更高版本，并且会找到你已有的一个。

• macOS / Linux 先尝试 python3，然后从 python3.14 向下到 python3.10，因此当 python3 解析为 macOS 较旧的系统版本时，Homebrew Python 仍然有效。

• Windows 先尝试 py -3（Python 启动器），然后尝试 python、python3 和带版本号的名称。每个候选都必须运行并报告自己的版本才算数，这样才能避免选择 %LOCALAPPDATA%\Microsoft\WindowsApps 中的 Microsoft Store 占位符：它是一个真实的 python.exe，位于 PATH 上，但只会打开 Store。

如果你的 Python 位于任何搜索都无法猜到的位置（pyenv、conda、私有前缀），请指定名称：

GWS_PYTHON=/full/path/to/python3 bash google-workspace-mcp/install.sh

$env:GWS_PYTHON = 'C:\full\path\to\python.exe'
powershell -ExecutionPolicy Bypass -File .\google-workspace-mcp\install.ps1

-ExecutionPolicy Bypass 是有意包含在命令中的。 Windows 默认阻止下载的脚本；这会将例外应用于这一次运行，而不会更改机器的策略。

从 PowerShell 运行，而不是 Git Bash。 install.sh 会检测 Git Bash / MSYS 并停止，并指向 install.ps1，而不是注册一个原生 Claude Code 无法启动的 POSIX venv 路径。WSL 是真正的 Linux，继续使用 install.sh。

时区。 连接器读取机器的 IANA 时区，以便 cal_* 调用中的“下午 3 点”表示你所在位置的下午 3 点。Windows 以自己的方式命名时区（SA Western Standard Time），因此这通过 tzlocal 处理，安装程序会拉取它。设置 GWS_TIME_ZONE=America/Bogota 以覆盖。

打开 Claude Code，粘贴：

/plugin marketplace add adelaidasofia/google-workspace-mcp
/plugin install google-workspace-mcp@google-workspace-mcp

你仍然需要完成 SETUP.md 中的一次性 GCP 设置（v1 约 45 分钟，v2 的 Drive/Docs/Sheets 增量约 5 分钟），以便服务器有一个 client_secret.json 用于 OAuth。从 Claude Code 运行 gws_account_add 来授权你的第一个邮箱。

在 Windows 上，之后运行 install.ps1。 插件的 .mcp.json 使用 python3 启动服务器，而插件清单无法说“除了 Windows，使用这个”。在 Windows 上，python3 要么不存在，要么是 Microsoft Store 占位符，因此连接器已注册但永远不会启动。install.ps1 会将其重新注册到绝对解释器路径，这在每个平台上都是明确的。

请参阅 SETUP.md 了解一次性 GCP 设置（v1 约 45 分钟，v2 启用 Drive/Docs/Sheets 增量约 5 分钟）。

设置后：

pip3 install --break-system-packages -r requirements.txt

注册到 Claude Code

添加到项目的 .mcp.json（或 ~/.claude.json 以全局访问）：

"google-workspace": {
  "type": "stdio",
  "command": "python3",
  "args": ["/path/to/google-workspace-mcp/server.py"]
}

在 Windows 上，给出真实解释器的完整路径，而不是裸名称——那里的 python3 通常是 Microsoft Store 占位符，它可以正常解析但永远不会运行 Python：

"google-workspace": {
  "type": "stdio",
  "command": "C:\\Users\\you\\google-workspace-mcp\\.venv\\Scripts\\python.exe",
  "args": ["C:\\Users\\you\\google-workspace-mcp\\server.py"]
}

从 v1 → v2 升级

v2 添加了 Drive + Docs + Sheets 作用域。每个授权账户必须重新 OAuth 一次，以便 Google 授予新作用域。请参阅 SETUP.md 步骤 6b。

路线图

• v3：Gmail 过滤器、假期回复、推送通知（Gmail Watch）、Calendar ACL/委派、Slides、Forms、Tasks

• v4：跨服务的批量请求、Drive 修订

相关 MCP

同一作者，同一架构模式（FastMCP、写入时草稿+确认（如适用）、保险库自动导出、MIT）：

• slack-mcp — 多工作区 Slack

• imessage-mcp — macOS iMessage

• whatsapp-mcp — 通过 whatsmeow 的 WhatsApp

• apollo-mcp — Apollo.io CRM + 序列

• substack-mcp — Substack 写作 + 分析

• luma-mcp — lu.ma 活动

• parse-mcp — markitdown / Docling / LlamaParse 路由器

• rescuetime-mcp — RescueTime 生产力数据

• graph-query-mcp — 保险库知识图谱查询

• graph-autotagger-mcp — 来自图谱的 wikilink 建议

• investor-relations-mcp — 种子轮融资管道跟踪器

• vault-sync-mcp — 双向保险库同步

遥测

此插件在给定机器上的 Claude Code 会话中首次加载时，会向 myceliumai.co 发送一个匿名安装信号。

发送的内容：

• 插件名称（例如 slack-mcp）

• 插件版本（例如 0.1.0）

不发送的内容：

• 没有用户标识符、姓名、电子邮件、令牌或 API 密钥

• 没有文件路径、消息内容或你工作中的任何内容

• 去重处理后不存储 IP 地址

原因： 帮助维护者了解人们实际安装了哪些插件，以便将注意力集中在被使用的插件上。

选择退出： 在启动 Claude Code 之前设置环境变量 MYCELIUM_NO_PING=1。该钩子将完全跳过网络调用。已经 ping 过的安装会在 ~/.mycelium/onboarded-<plugin> 留下一个标记文件——如果你想重置状态，请删除它。

许可证

MIT

由 Mycelium AI 构建。完整安装或团队版本请访问 diazroa.com。