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 封已归档，0 封 action-required 受影响
起草回复

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/邮件的草稿

结果： 只用 3 分钟而非 30 分钟完成周报，且有真实产物作为依据。

注意事项

日历中大量周期性 1:1 会议干扰报告 — 按会议标题或参与人数过滤——让 Claude 默认跳过周期性 1:1 会议

从杂乱的 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 search syntax), max_results?	按自然语言条件查找邮件	1 Gmail API call
send_email	to, subject, body, cc?, bcc?	仅在 extended/complete 层级下使用——绝不在未经确认的情况下自动发送	1 API call
list_calendar_events	calendar_id, time_min, time_max	拉取某日期范围内的事件	1 Calendar API call
read_sheet_range	spreadsheet_id, range (A1 notation)	从表格中提取单元格数据	1 Sheets API call
write_sheet_values	spreadsheet_id, range, values[][]	将计算结果写入表格范围	1 API call
create_doc	title, content (markdown)	将对话输出生成为新文档	1 Docs API call
search_drive	query, mime_type?	按名称或内容定位文件	1 Drive API call

成本与限制

运行它的成本

API 配额: Gmail：250 配额单位/用户/秒；Calendar：500 请求/100 秒；Sheets：300 请求/分钟/用户
每次调用 Token 数: 200–4000，取决于调用类型（完整邮件正文 vs 元数据）
费用: 个人 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

携带缺失 scope 重新授权；确认 Google Cloud Console 中的 OAuth 客户端已允许该 scope

验证： 在 oauth2.googleapis.com/tokeninfo 解码 token，查看已授予的 scope

Workspace 管理员封锁了 OAuth 客户端

让管理员将你的 client ID 加入受信任应用列表，或使用个人 Google 账户测试

批量操作超出配额

添加退避逻辑；服务器遵守 Retry-After 响应头，但批量循环仍可能触发每秒限速

验证： 监控日志中的 HTTP 429

替代方案