用 Google Workspace MCP v2 让智能体接管邮箱与日历：120+ 工具、OAuth 2.1 多用户与工具分级实操

# 1) 启用计划使用的服务 API
#    （官方 quick-start 提供逐项一键启用链接，也可命令行批量开）
gcloud services enable gmail.googleapis.com calendar-json.googleapis.com \
  drive.googleapis.com docs.googleapis.com

# 2) 控制台：APIs & Services → Credentials → Create Credentials
#    → OAuth client ID
#    本机调试选「Desktop app」；HTTP 部署选「Web application」，
#    重定向 URI 填：http://localhost:8000/oauth2callback

# 3) 复制 client id 与 client secret（或下载 client_secret.json）

官方 quick-start（workspacemcp.com/quick-start）有带截图的五分钟全流程，每一步该点哪、scope 怎么生成都覆盖了。scope 不用手工罗列——按你启用的服务与启动参数自动推导，这也是「只开要用的服务」省心的原因之一。

# 1. 凭证
export GOOGLE_OAUTH_CLIENT_ID="..."
export GOOGLE_OAUTH_CLIENT_SECRET="..."

# 2. 启动 —— 三档工具分级选一档
uvx workspace-mcp --tool-tier core       # 精简集
uvx workspace-mcp --tool-tier extended   # core + 管理操作
uvx workspace-mcp --tool-tier complete   # 全量 120+

# 或按服务精挑
uvx workspace-mcp --tools gmail drive calendar

uvx 会即时拉起带全部依赖的运行环境，你不需要装任何 Python 包。服务起来后，从 MCP 客户端发起连接时会弹 Google 授权页，账号确认、scope 确认，然后就能在客户端的工具列表里看到 Workspace 相关工具。

# Claude Desktop / 网页 / 手机：HTTP 模式 + Connector（官方推荐路径）
#   Settings → Connectors → Add custom connector
#   地址填 http://localhost:8000/mcp

# Claude Code：先把服务以 HTTP 模式跑起来，然后
claude mcp add --transport http workspace-mcp http://localhost:8000/mcp

# 可选：装官方附带的技能包，改善 Workspace 工具路由
ln -s "$(pwd)/skills/managing-google-workspace" ~/.claude/skills/managing-google-workspace

streamable HTTP 是官方推荐的通道，旧客户端没有 Connector 能力的走 stdio 配置（FAQ 里有指引）。ChatGPT 走 Developer Mode 接入，VS Code、LM Studio、Open WebUI 等任意 MCP 客户端都能用同一套 HTTP 或 stdio 配置。附带技能包是个加分项：里面写好了「什么任务该用哪组工具」的路由经验，装上后工具命中率明显更稳。

export MCP_ENABLE_OAUTH21=true
export GOOGLE_OAUTH_CLIENT_ID="..."
export GOOGLE_OAUTH_CLIENT_SECRET="..."
# 或者用 GOOGLE_CLIENT_SECRET_PATH 指向 client_secret.json
# （环境变量优先级更高）
export WORKSPACE_MCP_PORT=8000
export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:8000/oauth2callback"
export OAUTHLIB_INSECURE_TRANSPORT=1

# OAuth 2.1 要求 HTTP 传输
uvx workspace-mcp --transport streamable-http --tool-tier core

这个形态下每个用户用自己的 Google 账号走一遍授权，token 由服务端代理统一管理——适合团队共享一个内部部署，一人配服务、全员直接用。客户端凭 PKCE 连接，secret 始终留在服务端，不会随客户端配置扩散。

# 列出当前服务器的工具
uv run workspace-cli list

# 直接调用一个工具
uv run workspace-cli call search_gmail_messages query="is:unread" max_results=5

# 全局安装后当普通命令用（在仓库目录内执行）
uv tool install .

CLI 自带加密磁盘缓存的 OAuth token——认证一次，之后脚本随便跑。这是把 Workspace 操作接进 shell 脚本、定时任务、CI 流水线的入口：每日晨会前自动汇总今日日程、每周把未读重要邮件归档到 Drive，都从这两条命令长出来。

docker build -t workspace-mcp .
docker run -p 8000:8000 workspace-mcp

# 生产要点（Advanced Deployment 文档）：
# 1) 无状态模式：零磁盘写入，适配受限容器环境
# 2) token 存储后端：memory / disk / Valkey 或 Redis（分布式）
# 3) 只读起步：--read-only，再按服务开 --permissions
# 4) 服务账号 + 域级委派：按请求模拟用户，配域白名单
# 5) 可信网关身份：Pomerium / Cloudflare Access / oauth2-proxy
# 6) 调优变量：WORKSPACE_MCP_GOOGLE_API_WORKERS、
#    WORKSPACE_MCP_GOOGLE_API_TIMEOUT_SECONDS 等，见环境变量参考

v2.1.0 的几个增量值得点名：Gmail 转发草稿（对既有邮件起草转发）、可选的 GCS 文件后端（无状态部署存附件）、超时从 30 秒恢复到 60 秒（慢查询场景）。安全面上做得也比较自觉：本地文件读取默认限定托管附件目录，validate_file_path() 始终拦截 .env 系列文件与 ~/.ssh、~/.aws 等凭证目录——即便放宽 ALLOWED_FILE_DIRS 也绕不过这层。