MCP
Google Workspace MCP
用 MCP 和命令行让代理使用 Gmail、日历、文档、表格和云端硬盘等 Workspace 服务。
taylorwilsdon/google_workspace_mcp 是 MIT 许可的 MCP 服务器和命令行工具,用来让代理使用 Gmail、日历、文档、表格、幻灯片、Chat、Forms、Tasks、Search 和 Drive。它操作的是你的 Google 账号范围。
用专门的测试账号或最小权限的 OAuth 范围开始,不要一上来授权整个组织的邮箱和网盘。发送邮件或改共享设置之前必须人工确认。
推荐来源:
- @beamnxw 在 2026 年 9 月 15 日 的帖子里提到了这个项目(数字采集于 2026 年 11 月 15 日:633 次喜欢,105 次转发)。
本页是导读,不是原文。
解决什么问题
Google Workspace MCP(仓库 taylorwilsdon/google_workspace_mcp,PyPI 包名 workspace-mcp)让编码代理通过 MCP 调用 Gmail、日历、云端硬盘、文档、表格、幻灯片、表单、任务、通讯录、Chat 等 Workspace 服务。它操作的是你授权过的 Google 账号,而不只是本地文件。
官方文档把自托管服务器和名为 Workspace MCP Cloud 的托管服务分开介绍。本文只写开源仓库这条自托管路径:你在自己的 Google Cloud 项目里创建 OAuth 客户端,服务器用这份凭证去调 Google API。不要把托管产品的接入步骤套用到本地安装上。
适合谁
适合已经有 MCP 客户端(例如 Claude Code、Claude Desktop、VS Code),并希望代理在明确授权后读写自己的 Workspace 数据的人。它使用 MIT 许可,是独立开源项目,与 Google 没有隶属关系。
它不适合一上来就接到公司组织的生产邮箱或共享网盘。权限范围可以开到发信、改日历、改云端硬盘,误操作的代价很高。请先用测试账号,或把范围收得很窄。
怎么装
核验日期为 2026-11-15(Asia/Shanghai)。命令来自仓库 README 和官方 Quick Start(页面标明与 v2.5.0 同步,日期为 2026 年 11 月 14 日)。
Python 版本在官方材料里并不完全一致:仓库 README 的徽章和 pyproject.toml 写的是 Python 3.11 或更新;Quick Start 写的是 Python 3.10 或更新,并需要 uv。本文不擅自统一,请按你跟随的文档安装,并在本机确认 python3 --version。
先在 Google Cloud Console 建一个 OAuth 客户端,并只启用你打算用的 API。Quick Start 把客户端类型区分得很清楚:本地 CLI 和 stdio 多用 Desktop application;托管 HTTP、反向代理或浏览器客户端用 Web application,且授权来源与回调地址必须和用户实际访问的地址一致。本地仅 HTTP 开发时,官方示例会设置 OAUTHLIB_INSECURE_TRANSPORT=1,这不应出现在生产环境。
export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
# 建议先用 core 档,需要时再扩大
uvx workspace-mcp --tool-tier core
# 现代客户端推荐 streamable HTTP;默认监听 http://localhost:8000/mcp
uvx workspace-mcp --transport streamable-http --tool-tier core多用户 OAuth 2.1 需要 HTTP 传输,且不能与 --single-user 一起用:
export MCP_ENABLE_OAUTH21=true
uvx workspace-mcp --transport streamable-http --tool-tier core也可用 --tools gmail drive calendar 只加载部分服务,或加 --read-only、--permissions 限制范围。官方文档举例:--permissions gmail:send drive:readonly。--read-only 会申请只读范围并隐藏写入工具,不能与 --permissions 同时使用。
Claude Code
先按上一节启动 HTTP 服务。仓库 README 给出的命令是:
claude mcp add --transport http workspace-mcp http://localhost:8000/mcp同一天的 Quick Start 把服务器名称写成 workspacemcp。本文不擅自统一名称,请按你正在看的那一页来写,再用客户端的 MCP 列表确认连接。可选技能见仓库 skills/managing-google-workspace,不是必装项。
Claude Desktop
官方推荐走自定义连接器:Settings → Connectors → Add custom connector,填入服务器地址。分步截图见 Connector 指南。stdio 只作为没有连接器的旧客户端后备。
VS Code
官方 Quick Start 把下面这段写入 .vscode/mcp.json 或用户级 mcp.json:
{
"servers": {
"workspacemcp": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}命令行工具 workspace-cli 可列出并调用已注册工具。请从仓库执行 uv tool install . 再使用;官方明确警告不要用 uvx workspace-cli,因为 PyPI 上有一个弃用的同名包。
一个实际例子
下面的步骤是为本文写的核验流程,不是官方固定口令。本次没有对真实账号实跑,因此不编造邮件列表。
- 用测试账号完成 OAuth,确认只启用了你需要的 API,并尽量以
core或--read-only启动。 - 在已连接的客户端发送:
List my five most recent unread Gmail messages. Do not send, delete, or change labels. - 也可以在已经装好的命令行里执行:
workspace-cli call search_gmail_messages query="is:unread" max_results=5- 请自己核对这些主题是否与网页版 Gmail 一致。若工具列表比预期更宽,先检查启动参数里的档位和权限,再继续。
常见坑
- 把范围开得太大。
--permissions和--read-only会同时影响向 Google 申请的范围和暴露给模型的工具。Gmail 的send、full以及 Drive / Calendar 的full都能改真实数据。官方安全说明还提醒:邮件、文档和日程里可能藏有提示词注入,写入工具要有意选择。 - 用错 OAuth 客户端类型,或回调地址与实际访问地址不一致。Quick Start 把 Desktop 与 Web application 的适用场景写得很清楚;Web 客户端必须配置匹配的授权来源和
/oauth2callback。 - 误删带有参会者的日历事件。issue #1312(2026-11-15 仍为 open)指出,
manage_event的删除动作即使加上send_updates="none",仍可能把有客人的会议删掉。删除或改共享设置前应人工确认。 - 把密钥写进仓库。官方要求不要提交
.env、client_secret.json或.credentials/。生产部署应使用 HTTPS 和 OAuth 2.1。 - Python 版本对不上。若
uvx启动失败,先核对你读的是pyproject.toml的 3.11+ 还是 Quick Start 的 3.10+,再检查本机 Python,不要自行「取平均」。
FAQ
这和 Workspace MCP Cloud 是一回事吗?
不是同一条安装路径。Cloud 是官方站点上的托管服务,有自己的套餐和接入方式。本文写的是开源仓库里的自托管服务器:你使用自己的 Google Cloud OAuth 客户端。不要把托管服务的 FAQ 直接套到 uvx workspace-mcp 上。
怎样把权限降到最低?
官方建议先用 --tool-tier core,再用 --tools 只加载需要的服务。若暂时不需要写入,加 --read-only;若要按服务给不同级别,用 --permissions(例如 gmail:readonly)。两者不能并用。还可用 --disabled-tools 单独去掉某个工具。
需要付费的 Google Workspace 账号吗?
README 写明免费 Google 账号和 Google Workspace 方案都支持,部分应用(例如 Chat)在 Workspace 方案上选项更全。本文没有独立核验各套餐的功能差异,请以 Google 和项目文档为准。MCP 服务器本身是 MIT 许可的开源软件。
为什么授权后工具调用仍然失败?
先确认相应 Google API 已在同一项目中启用,OAuth 客户端类型和回调地址与传输方式匹配,并且当前进程加载的工具档位包含你要调用的工具。issue #1195 还记录过 OAuth 2.1 授权请求缺少 scope 时,只拿到身份范围、随后工具调用失败的情况(该 issue 已关闭)。
可以用 uvx 运行 workspace-cli 吗?
官方明确说不要。请从仓库执行 uv tool install .,或在仓库里用 uv run workspace-cli。uvx workspace-cli 可能装到一个占用同名的弃用 PyPI 包。
来源与许可
仓库 taylorwilsdon/google_workspace_mcp 使用 MIT 许可。本文依据 2026-11-15 查阅的 README、Quick Start 和 文档中的权限说明,用自己的话写成,供 CQBase 上下文库使用。若安装命令、Python 要求或权限档位有变,以这些官方材料为准。