# Google Workspace MCP

Canonical: https://cqbase.net/zh/entry/google-workspace-mcp
Chinese: https://cqbase.net/zh/entry/google-workspace-mcp
English: https://cqbase.net/en/entry/google-workspace-mcp

> 用 MCP 和命令行让代理使用 Gmail、日历、文档、表格和云端硬盘等 Workspace 服务。

taylorwilsdon/google_workspace_mcp 是 MIT 许可的 MCP 服务器和命令行工具，用来让代理使用 Gmail、日历、文档、表格、幻灯片、Chat、Forms、Tasks、Search 和 Drive。它操作的是你的 Google 账号范围。

用专门的测试账号或最小权限的 OAuth 范围开始，不要一上来授权整个组织的邮箱和网盘。发送邮件或改共享设置之前必须人工确认。

推荐来源：

- [@beamnxw](https://x.com/beamnxw/status/2099797510080360913) 在 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](https://github.com/taylorwilsdon/google_workspace_mcp) 和官方 [Quick Start](https://workspacemcp.com/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](https://console.cloud.google.com/) 建一个 OAuth 客户端，并只启用你打算用的 API。Quick Start 把客户端类型区分得很清楚：本地 CLI 和 stdio 多用 Desktop application；托管 HTTP、反向代理或浏览器客户端用 Web application，且授权来源与回调地址必须和用户实际访问的地址一致。本地仅 HTTP 开发时，官方示例会设置 `OAUTHLIB_INSECURE_TRANSPORT=1`，这不应出现在生产环境。

```bash
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` 一起用：

```bash
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 给出的命令是：

```bash
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 指南](https://workspacemcp.com/guides/claude-connectors)。stdio 只作为没有连接器的旧客户端后备。

**VS Code**

官方 Quick Start 把下面这段写入 `.vscode/mcp.json` 或用户级 `mcp.json`：

```json
{
  "servers": {
    "workspacemcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

命令行工具 `workspace-cli` 可列出并调用已注册工具。请从仓库执行 `uv tool install .` 再使用；官方明确警告不要用 `uvx workspace-cli`，因为 PyPI 上有一个弃用的同名包。

## 一个实际例子

下面的步骤是为本文写的核验流程，不是官方固定口令。本次没有对真实账号实跑，因此不编造邮件列表。

1. 用测试账号完成 OAuth，确认只启用了你需要的 API，并尽量以 `core` 或 `--read-only` 启动。
2. 在已连接的客户端发送：`List my five most recent unread Gmail messages. Do not send, delete, or change labels.`
3. 也可以在已经装好的命令行里执行：

```bash
workspace-cli call search_gmail_messages query="is:unread" max_results=5
```

4. 请自己核对这些主题是否与网页版 Gmail 一致。若工具列表比预期更宽，先检查启动参数里的档位和权限，再继续。

## 常见坑

- 把范围开得太大。`--permissions` 和 `--read-only` 会同时影响向 Google 申请的范围和暴露给模型的工具。Gmail 的 `send`、`full` 以及 Drive / Calendar 的 `full` 都能改真实数据。官方安全说明还提醒：邮件、文档和日程里可能藏有提示词注入，写入工具要有意选择。
- 用错 OAuth 客户端类型，或回调地址与实际访问地址不一致。Quick Start 把 Desktop 与 Web application 的适用场景写得很清楚；Web 客户端必须配置匹配的授权来源和 `/oauth2callback`。
- 误删带有参会者的日历事件。[issue #1312](https://github.com/taylorwilsdon/google_workspace_mcp/issues/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](https://github.com/taylorwilsdon/google_workspace_mcp/issues/1195) 还记录过 OAuth 2.1 授权请求缺少 `scope` 时，只拿到身份范围、随后工具调用失败的情况（该 issue 已关闭）。

### 可以用 uvx 运行 workspace-cli 吗？

官方明确说不要。请从仓库执行 `uv tool install .`，或在仓库里用 `uv run workspace-cli`。`uvx workspace-cli` 可能装到一个占用同名的弃用 PyPI 包。

## 来源与许可

仓库 [taylorwilsdon/google_workspace_mcp](https://github.com/taylorwilsdon/google_workspace_mcp) 使用 MIT 许可。本文依据 2026-11-15 查阅的 README、[Quick Start](https://workspacemcp.com/quick-start) 和 [文档中的权限说明](https://workspacemcp.com/docs)，用自己的话写成，供 CQBase 上下文库使用。若安装命令、Python 要求或权限档位有变，以这些官方材料为准。

## 收录信息

- 作者: taylorwilsdon
- 许可证: MIT
- 来源: https://github.com/taylorwilsdon/google_workspace_mcp
- 收录: 2026-11-15
- GitHub 星标: 3519（采集 2026-11-15）

