taylorwilsdon/google_workspace_mcp · 上手攻略
- 仓库：taylorwilsdon/google_workspace_mcp
- 链接：https://github.com/taylorwilsdon/google_workspace_mcp
- 分类：mcp-server · productivity
- 作者：Jay
- 更新：2026-08-11
这是什么
Google Workspace MCP Server（workspace-mcp）是目前功能最完整的 Google Workspace MCP 服务器，通过 MCP（Model Context Protocol）协议将 AI 助手连接到 Google 全套生产力工具——覆盖 Gmail、Drive、Calendar、Docs、Sheets、Slides、Forms、Tasks、Contacts、Chat 十大服务，共 120+ 工具，全部通过一个 MCP Server 暴露。
核心定位：让 AI 助手能够读写、搜索、创建、分享你的 Google 工作区数据，且支持 OAuth 2.1 多用户认证和容器化无状态部署。
⚠️ 版本要求：Python 3.10+，MCP 客户端需支持 stdio 或 streamable HTTP 传输。
解决什么问题
主流 AI 助手（Claude、ChatGPT）连接 Google Workspace 的现有方案存在以下局限：
| 痛点 | 现有方案 | workspace-mcp |
|---|---|---|
| 工具数量少 | Google 官方插件仅覆盖 3-5 个 API | 120+ 工具，覆盖全部主要服务 |
| 不支持细粒度编辑 | 只读或只能追加 | 支持文档样式、表格格式、评论、分享权限等 |
| 无多用户认证 | 单用户 token | OAuth 2.1 多用户，组织级部署 |
| 无企业安全合规 | 数据经过第三方 | 数据只走用户自己的 OAuth，不出 Google API |
| 不支持沙箱/无状态 | 依赖本地磁盘 | 零磁盘写入，适合容器环境 |
快速安装
方式一：uvx 一行命令（推荐，无需 clone）
# 安装（自动下载最新 release）
pip install workspace-mcp # 或 uvx workspace-mcp --help
# 验证工具列表
workspace-cli list
⚠️ workspace-cli 安装：
uv tool install .（在仓库根目录），不要用pip install workspace-cli——PyPI 有一个同名废弃包。
方式二：Docker 部署
docker run -p 8000:8000 \
-e GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com" \
-e GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret" \
-e MCP_ENABLE_OAUTH21=true \
ghcr.io/taylorwilsdon/workspace-mcp:latest \
--transport streamable-http \
--tool-tier complete
核心配置
第一步：创建 Google OAuth Client（Google Cloud Console）
- 前往 Google Cloud Console → APIs & Services → Credentials
- 创建 OAuth 2.0 Client ID： - Desktop app（本地 CLI / stdio）：选「Desktop app」类型 - Web application（HTTP 部署 + 反向代理）：选「Web application」类型
- 下载 JSON，导出环境变量：
export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
# 本地开发（允许 http://）
export OAUTHLIB_INSECURE_TRANSPORT=1
第二步：启动 MCP Server
# 最小启动（核心工具层）
uvx workspace-mcp --tool-tier core
# 完整工具层
uvx workspace-mcp --tool-tier complete
# 指定传输方式
uvx workspace-mcp --transport streamable-http --tool-tier core
# 多用户 OAuth 2.1
export MCP_ENABLE_OAUTH21=true
uvx workspace-mcp --transport streamable-http --tool-tier core
第三步：连接 AI 客户端
# Claude Code
claude mcp add --transport http workspacemcp http://localhost:8000/mcp
# VS Code (mcp.json)
{
"servers": {
"workspacemcp": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}
# Claude Desktop：Settings → Connectors → Add custom connector → 粘贴 URL
工具层速查
| 服务 | 工具数 | 核心工具 |
|---|---|---|
| Gmail | 15+ | search_messages, send_email, create_draft, add_label, apply_filter |
| Drive | 16+ | search_files, create_file, share_file, import_office |
| Calendar | 7+ | search_events, create_event, get_free_busy, create_out_of_office |
| Docs | 19+ | search_docs, create_doc, edit_document, add_comment, export_doc |
| Sheets | 14+ | search_spreadsheets, update_range, append_rows, apply_formatting |
| Slides | 12+ | search_presentations, create_slide, update_text, share_presentation |
| Forms | 6+ | create_form, add_form_question, get_form_responses |
| Tasks | 5+ | search_tasks, create_task, mark_complete |
| Chat | 10+ | send_message, create_space, list_members |
常用命令示例
# 搜索 Gmail
workspace-cli call search_gmail_messages query="is:unread from:github" max_results=5
# 创建日历事件
workspace-cli call create_calendar_event \
summary="团队周会" \
start_time="2026-08-12T10:00:00Z" \
end_time="2026-08-12T11:00:00Z" \
attendees='["colleague@example.com"]'
# 在 Google Docs 中查找内容
workspace-cli call search_documents query="项目总结"
# 创建 Google Sheet 并写入数据
workspace-cli call create_spreadsheet title="Q3 数据报告"
workspace-cli call update_spreadsheet_range \
spreadsheet_id="YOUR_SPREADSHEET_ID" \
range="A1:C3" \
values='[["项目", "指标A", "指标B"], ["Alpha", 120, 95], ["Beta", 88, 102]]'
三层工具分级
| 层级 | 工具范围 | 适用场景 |
|---|---|---|
| core | 搜索、读取、基础创建/修改 | 最小权限、API 配额受限环境 |
| extended | core + 标签/文件夹管理、批量操作、高级搜索 | 日常办公、多用户协作 |
| complete | 全部 API 表面，含评论、发布设置、管理功能 | 企业管理、合规审计 |
层级是累积的：complete 包含 core + extended。
典型适用场景
- AI 助手邮件管理：让 Claude 自动整理 Gmail 收件箱、按标签归档、生成邮件摘要
- 日历自动化：Claude 根据邮件内容自动创建会议邀请并发送日历给参与者
- 文档协作流：Claude 读取 Google Docs 内容 → 润色修改 → 写回文档（保留格式和评论）
- 报表生成：Claude 读取 Google Sheets 数据 → 分析 → 生成 PPT/文档报告
- 跨服务工作流：邮件触发任务创建 → 日历安排 → 任务完成通知，全链路 AI 自动化
坑与注意
-
OAuth 首次认证需要浏览器：workspace-cli 首次调用会触发浏览器 OAuth 流程，完成后 token 加密缓存在
~/.workspace-mcp/cli-tokens/，后续无需重复认证。 -
桌面客户端 ≠ Web 客户端：在 Google Cloud Console 创建 OAuth Client 时，Desktop app 类型对应本地 CLI，Web application 类型对应 HTTP 部署——不要混用，否则认证会失败。
-
MCP_ENABLE_OAUTH21 要求 HTTP 传输：OAuth 2.1 无法与
--single-user或 stdio 传输模式同时启用；如需多用户，必须用 streamable-http。 -
敏感文件默认阻止读取：
validate_file_path()默认阻止~/.ssh/、~/.aws/、.env*文件，扩展ALLOWED_FILE_DIRS时注意不要误开凭证路径。 -
API 配额：所有操作受 Google API 配额限制，高频调用场景（如批量文件处理）建议加
--read-only模式或设置请求间隔。 -
MCP 客户端兼容性：streamable HTTP 是推荐传输方式；stdio 模式为 legacy fallback，仅在旧版 MCP 客户端无法使用 HTTP 时才用。
-
MIT 许可证：可商用、可再分发、无 CLA、无开源核心限制。
与同类对比
| 工具 | 工具覆盖 | 多用户 | 传输方式 | 许可证 |
|---|---|---|---|---|
| workspace-mcp | 120+ 工具/10 服务 | ✅ OAuth 2.1 | stdio + streamable HTTP | MIT |
| @modelcontextprotocol/server-gmail | 仅 Gmail | ❌ | stdio | MIT |
| googl-mcp | Gmail/Drive/Calendar | 部分 | stdio | AGPL |
| Google AI Studio 插件 | 基础 Gmail/Docs | ❌ | 插件内置 | 专有 |
workspace-mcp 的核心优势：工具数量最多（120+）、多用户认证最完整（OAuth 2.1）、覆盖服务最全（10 大服务）、唯一支持无状态容器部署。
一句话结论
需要让 AI 助手真正操控你的 Google 工作区数据？workspace-mcp 是目前功能最完整的 MCP 方案——120+ 工具覆盖 Gmail 到 Chat 全套，一行命令启动，OAuth 2.1 多用户认证，开箱即用。
来源与引用
- 仓库 README：https://github.com/taylorwilsdon/google_workspace_mcp
- 官方 Quick Start：https://workspacemcp.com/quick-start
- 完整文档：https://workspacemcp.com/docs
- 部署指南：https://workspacemcp.com/docs/deployment
- 客户端配置指南：https://workspacemcp.com/guides
- FAQ & 故障排除：https://workspacemcp.com/welcome/faq
- PyPI（workspace-mcp）：https://pypi.org/project/workspace-mcp
- MIT 许可证：https://opensource.org/licenses/MIT