workspace-mcp — Google Workspace MCP 集成

[SozoPC] 环境笔记。相关：decision-log（2026-08-01 条目）、google-workspace-agent-spec。

概述

• 来源：GitHub taylorwilsdon/google_workspace_mcp（⭐2949 / 913 forks / MIT）— 12 个 Google Workspace 服务、120+ 工具
• 版本：workspace-mcp 1.23.0（uv 安装），产出两个可执行：workspace-mcp（MCP server）+ workspace-cli（连接客户端）
• 二进制位置：C:\Users\Sozo\.local\bin\workspace-mcp
• Hermes 内工具名前缀：mcp__google_workspace__*（共 121 个，gateway 重启后加载）

Hermes 配置（config.yaml → mcp_servers.google_workspace）

google_workspace:
  command: C:/Users/Sozo/.local/bin/workspace-mcp
  args: [--single-user, --tool-tier, complete]
  env: {PYTHONPATH: ''}
  timeout: 120

• 配置写在 D:\hermes\config.yaml（有安全保护，patch 工具会被拒 → 用 hermes config set 后用 Python 直接写 YAML 修正类型：hermes config set 会把 args/env 存成字符串，必须改回列表/字典）

⚠️ 核心坑：PYTHONPATH 污染

• Hermes 环境注入 PYTHONPATH=D:\hermes\hermes-agent;...\venv\Lib\site-packages → workspace-mcp 的独立 Python import 到 Hermes venv 的旧 pydantic（缺 pydantic_core 二进制）→ 启动报错
• 修复：env: {PYTHONPATH: ''} 清空

OAuth 授权（✅ 已完成 2026-08-01，含上游 bug 绕过）

⚠️ 原生授权流程有 2 个上游 bug，无法直接完成；完整手动绕过流程见 skill D:\hermes\skills\devops\workspace-mcp-auth（[SozoPC]）。

• 凭据目录：~/.google_workspace_mcp/credentials/<email>.json（LocalDirectoryCredentialStore，JSON 文件非 SQLite；字段：token / refresh_token / token_uri / client_id / client_secret / scopes / expiry）→ 已写入 ida.czia@gmail.com.json
• 凭据来源：环境变量 GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET（914687008998-1n6dr08qsi7qifs8uvcnqitgqogsqk9s.apps.googleusercontent.com），或根目录 client_secret.json（D:\hermes\google_client_secret.json 已复制过去）
• 触发方式：stdio 模式调用 start_google_auth 工具（参数 service_name + user_google_email）→ 返回授权 URL（redirect localhost:8001/oauth2callback）→ 需进程保持存活 + 回调服务器监听
• ⚠️ MCP_ENABLE_OAUTH21=true + streamable-http 模式会禁用 start_google_auth 工具并立即退出 — 不要走那条路
• 端口：8000 被其他进程占用（PID 16864），workspace-mcp 自动回退 8001

上游 bug 1 — PKCE：workspace-mcp 生成的 code_challenge 报 “Code Challenge must be base64 encoded”（Google 拒绝）。 上游 bug 2 — redirect_uri_mismatch：OAuth client 白名单只有 https://quotation.hsdesign.biz/auth/callback、http://localhost:5173/auth/callback、https://quotation.hsdesign.biz/api/auth/callback — 没有 localhost:8001。

手动绕过（已验证成功）：

1. 手动生成合法授权 URL：手动 PKCE（code_verifier/code_challenge base64url 无 padding）+ redirect_uri 用白名单里的 http://localhost:5173/auth/callback
2. 用户浏览器授权（ida.czia@gmail.com，全 scope）→ 回调 URL 里拿到 code
3. 用 code + code_verifier 调 https://oauth2.googleapis.com/token 兑换 access + refresh token
4. 按上面 JSON 格式写入 ~/.google_workspace_mcp/credentials/ida.czia@gmail.com.json

工具参数坑（Sheets）：create_sheet 用 sheet_name（不是 title）；modify_sheet_values 用 range_name + values（JSON 字符串/string 2D 数组，不是 Python 值）；search_gmail_messages 没有 max_results 参数。

已验证

• ✅ stdio 握手正常（serverInfo google_workspace v3.4.5）
• ✅ Hermes 加载 121 工具（mcp__google_workspace__* 可用）
• ✅ 发邮件已验证：用原 Hermes google-workspace skill（D:\hermes\google_token.json，OAuth 已配好）发测试邮件成功 → ida.czia@gmail.com（message id 19fbb475cd86f97d）
• ✅ workspace-mcp 自带 OAuth 完成：凭据注入 ~/.google_workspace_mcp/credentials/ida.czia@gmail.com.json 后，search_gmail_messages 调用成功（Message ID 19fb657dc6efef83）— 121 工具全部可用
• ✅ Sheets 工具实战：create_spreadsheet / create_sheet / modify_sheet_values / format_sheet_range / read_sheet_values 已用于搭建 HS Design 报价系统（见 hsdesign-quotation-sheet-system）

备注

• 原 google-workspace skill 已按 Gemini Spark 的 Workspace Agent 规范升级（链接溯源、变更确认卡片、Gmail 线程感知、纯文本默认、日历严格时间边界）— 见 google-workspace-agent-spec
• 用户偏好：日常能力原 skill 已够用；workspace-mcp 完整授权是增强项，用户明确要求配完（现已完成 ✅）