google-workspace-mcp

用于 Gmail + Calendar + Drive + Docs + Sheets 的多账户、Token 高效 MCP。 构建此项目的初衷是官方 Claude 连接器仅支持一个账户，且默认返回完整的消息/文件正文。

为什么存在此项目

• 多账户：支持多个邮箱（工作 + 个人 + 联合创始人）的 OAuth。每个工具都接受一个 account 邮箱参数；别名通过“发送身份”（Send-As identities）处理。

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

• 基于钥匙串（Keychain）：刷新令牌存储在 macOS 钥匙串中，而非明文文件中。Vault 中没有令牌，任何仓库中也没有令牌。

工具 (v2, 61 个工具)

账户管理 (3)

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

• gws_account_list — 列出已授权账户及默认账户

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

Gmail (10)

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

• gmail_read — 读取单条消息或完整会话。正文可选。

• gmail_send — 发送邮件，支持可选的 from_alias 以使用“发送身份”

• gmail_draft — 创建草稿

• gmail_reply — 回复（保留会话 + 标题），支持可选的 reply_all

• gmail_labels_list — 列出所有标签

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

• gmail_archive — 批量归档（从收件箱移除）

• gmail_trash — 批量移至回收站

• gmail_sendas_list — 列出此邮箱上的“发送身份”

日历 (7)

• cal_list_calendars — 列出所有日历

• cal_list_events — 列出即将到来的活动（默认紧凑，verbose=True 可获取完整信息）

• cal_create_event — 创建活动，支持可选的 Google Meet 链接

• cal_update_event — 局部更新字段

• cal_delete_event — 删除

• cal_freebusy — 检查忙闲状态以进行日程安排

• cal_respond — 接受/拒绝/待定

云端硬盘 (18)

• drive_search — 自由文本或原始 Drive q-syntax 搜索。仅返回元数据响应。

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

• drive_list_folder — 文件夹的直接子项（'root' 代表我的云端硬盘）

• 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 — 将评论标记为已解决

文档 (9)

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

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

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

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

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

• docs_export — 导出为 markdown / pdf / docx / rtf / 纯文本

• docs_suggestions_list — 列出待处理的修订建议

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

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

表格 (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 验证

安装

请参阅 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"]
}

从 v1 升级到 v2

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

路线图

• v3：Gmail 过滤器、休假回复、推送通知 (Gmail Watch)、日历 ACL/委派、幻灯片、表单、任务

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

许可证

MIT