better-workspace-mcp

workspace

Google Workspace MCP — Docs、Drive、Calendar、Gmail、Sheets、Slides、Tasks、Chat、People、Forms

已于 2026-09-13 归档 — 此仓库已停止维护。请改用官方 Google Workspace API，而不是此 MCP 服务。现有安装仍可使用，但不会再收到更新或支持。

文档 · 安装 · 快速开始 · 社区

n24q02m 的姊妹项目（点击展开）

| 项目 | 标语 | 标签 | |---|---|---| | [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | AI Agent 在共享文件夹中彼此聊天——无需人工转发，也无需编排器，工... | 工具 | | [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | 适用于高效代码审查的知识图谱——语义搜索和调用-... | MCP | | [better-drive](https://github.com/n24q02m/better-drive) | 支持 `.driveignore` 过滤的双向 Google Drive 同步——基于 rclone 引擎，配备 Windows 系统托盘 | 工具 | | [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | 面向 AI Agent 的 IMAP/SMTP 邮件功能——读取、发送、整理文件夹并管理附件... | MCP | | [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | 适用于 Godot Engine 的复合 MCP 服务——提供 17 个复合工具，支持 AI 辅助游戏... | MCP | | [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | 面向 AI Agent、以 Markdown 为先的 Notion——页面、数据库、块和评论... | MCP | | [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | 可直接替换的 python-semantic-release 分支，内置发布安全防护（原...） | 工具 | | [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | 面向 AI Agent 的 Telegram——支持跨两种机器人...的消息、聊天、媒体和联系人 | MCP | | [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP 服务（Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...） | MCP | | [claude-plugins](https://github.com/n24q02m/claude-plugins) | 面向 n24q02m MCP 服务的 Claude Code 插件市场——安装网页搜索... | 市场 | | [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | 面向 AI Agent 的图像和视频理解与生成——支持 Gemini、Op... 等 | MCP | | [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | 用于通过 batchexecute API 批量操作 Jules 任务的 Chrome 扩展——... | 工具 | | [mcp-core](https://github.com/n24q02m/mcp-core) | 用于构建 MCP 服务的共享基础——Streamable HTTP 传输、OAuth... | MCP | | [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | 具备混合搜索和嵌入式同步功能的持久化 AI 记忆。开放、免费、无限... | MCP | | [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | 通过 ONNX Runtime 和 GGUF 实现轻量级 Qwen3 文本嵌入与重排序 | 库 | | [skret](https://github.com/n24q02m/skret) | 无需服务端的密钥管理。 | CLI | | [tacet](https://github.com/n24q02m/tacet) | 一种自蒸馏神经符号级联架构，可将大模型成本分摊到知识... | 工具 | | [web-core](https://github.com/n24q02m/web-core) | 用于搜索、抓取、HTTP 安全和 st... 的共享 Web 基础设施包 | 库 | | [wet-mcp](https://github.com/n24q02m/wet-mcp) | 面向 AI Agent 的开源 MCP 服务：网页搜索、内容提取和库... | MCP |

目录

• 安装
• 远程（HTTP 模式）
• 工具
• 快速开始
• 多账户
• 文档
• 部署
• 交接
• 贡献
• 许可证

安装

服务以两种模式运行：stdio（默认模式，单用户，使用你自己的 Google OAuth 客户端）和 HTTP（多用户，每位用户使用各自的 bearer token）。使用 stdio 时，将其添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "workspace": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/workspace@latest"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "<your-client-id>.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "<your-client-secret>"
      }
    }
  }
}

包名为 @n24q02m/workspace（原名为 @n24q02m/better-workspace-mcp；旧包会再发布一个最终版本，之后停止更新）。MCP Registry ID 仍为 io.github.n24q02m/better-workspace-mcp，旧命令 better-workspace-mcp 仍作为 workspace 的别名保留。

这两个值来自一个 Desktop app 类型的 OAuth 2.0 客户端，该客户端需在 Google Cloud Console 的“API 和服务 → 凭据”下创建。Desktop 是正确的类型，因为服务会在环回地址上接收授权重定向，而非在公共 URL 上接收。在同一项目中启用你计划调用的 Workspace API；如果授权同意屏幕尚未发布，请将自己添加为测试用户。

首次运行时，浏览器会打开 Google 授权同意屏幕；刷新令牌会加密后存储在你的机器上的 ~/.better-workspace/ 中（如果存在旧版 ~/.better-workspace-mcp/，则会作为备用路径读取），因此之后运行时无需再次授权。

同一服务也可以通过 HTTP 为多位用户提供服务——请参阅远程（HTTP 模式）。

通过 AI Agent 安装——将以下内容粘贴给你的 AI 编码 Agent：

按照以下步骤安装 MCP 服务 workspace： https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-workspace-mcp/setup-with-agent.md

远程（HTTP 模式）

除了 stdio，该服务还可以作为多用户 HTTP 服务运行。每个请求都会携带来自用户文件（WORKSPACE_USERS_FILE）的 bearer token；每位用户的 Google 凭据会保存在各自的存储桶中，并以该用户的命名空间为键，因此一次部署即可为多位用户提供服务，且他们无需共用账号。HTTP 账号的 Google 授权会在主机上进行，使用 workspace auth --user <namespace>。

将 MCP 客户端指向你部署服务的主机：

{
  "mcpServers": {
    "workspace": {
      "type": "http",
      "url": "https://<your-host>/mcp"
    }
  }
}

模式

只有两种模式，不多也不少。没有代理或守护进程模式：stdio 直接使用 MCP stdio 传输，不经过内部 HTTP 中转。

模式	选择方式	服务对象	Google OAuth 客户端
stdio	默认	一位用户，在其自己的机器上	Desktop app
http	--http、MCP_TRANSPORT=http 或 TRANSPORT_MODE=http	多位用户，每个用户命名空间对应一个凭据存储桶	Web application

两个 OAuth 客户端，不能共用一个

Google 会根据 OAuth 客户端的类型绑定重定向 URI，因此两种模式不能共用一个客户端。stdio 使用 Desktop 客户端，可以重定向到任意环回端口。HTTP 使用 Web 客户端。请将这两组凭据分别命名：如果一台同时运行 stdio 的机器将 GOOGLE_OAUTH_CLIENT_ID/_SECRET 指向 Web 客户端，就会导致所有 stdio 安装都无法正常工作。因此，docker-compose.http.yml 会以 GOOGLE_OAUTH_WEB_CLIENT_ID/_SECRET 读取 Web 凭据对，并在传入容器时重命名。

环境

变量	必填	作用
GOOGLE_OAUTH_CLIENT_ID	是	Web 客户端 ID。未设置时，服务将拒绝启动。
GOOGLE_OAUTH_CLIENT_SECRET	是	Web 客户端密钥。同上。
CREDENTIAL_SECRET	是	为每位用户的凭据存储派生加密密钥。未设置时，服务将拒绝启动，避免在用户授权过程中途失败。
WORKSPACE_USERS_FILE	HTTP 模式下必填	用户文件，用于将每个 bearer 令牌映射到一个用户命名空间（hull multi 身份验证）。未设置时使用 hull 的默认位置。
PORT	否	监听端口。0（默认值）会让 OS 分配一个可用端口。
HOST	否	绑定地址。默认绑定到环回地址，因此容器需要设置为 0.0.0.0。

凭据存储在本地磁盘的 ~/.better-workspace/ 下，该目录是容器中的数据卷。旧版 ~/.better-workspace-mcp/ 会作为备用位置读取。

此仓库中的 docker-compose.http.yml 是将这些变量写入可运行覆盖配置的示例。

工具

每个 Workspace 域都有一个复合工具，另有 config 和 help：

工具	功能范围
docs	Google Docs——getText、create、writeText、getSuggestions、replaceText、formatText
drive	文件和文件夹——search、findFolder、createFolder、moveFile、renameFile、trashFile、downloadFile、getComments
calendar	日历活动——listCalendars、listEvents、getEvent、createEvent、updateEvent、deleteEvent、respondToEvent、findFreeTime
gmail	邮件——search、get、send、createDraft、sendDraft、modify、batchModify、modifyThread、downloadAttachment、listLabels、createLabel
sheets	电子表格，仅支持读取——getText、getRange、getMetadata
slides	演示文稿——19 项操作，涵盖幻灯片、文本、形状、图片、表格和演讲者备注
tasks	任务列表和任务——listTaskLists、listTasks、createTask、updateTask、completeTask、deleteTask
chat	Google Chat——listSpaces、findSpaceByName、setUpSpace、getMessages、listThreads、sendMessage、sendDm、findDmByEmail
people	个人资料查询——getMe、getUserProfile、getUserRelations
forms	表单——create、get、batchUpdate、listResponses、getResponse
time	本地日期、时间和时区辅助工具（无需 Google 账号）
config	凭据状态和账号管理
help	任意工具的完整文档

使用 forms(action="batchUpdate") 向表单添加问题，而不是在 create 时添加；响应为只读，因为 Forms API 无法写入响应。表单的列出或删除操作通过 drive 完成。

快速开始

使用 config 工具检查凭据是否已就绪。首次授权前，它会报告 awaiting_setup；之后会显示服务当前使用的账号：

{ "action": "status" }

然后调用域工具。对于 docs，create 会返回新文档的 ID，getText 可读取该文档：

{ "action": "create", "title": "Notes", "content": "First line." }
{ "action": "getText", "documentId": "<id-from-create>" }

time、config 和 help 无需 Google 账号，因此即使尚未授权也能响应；time 是检查服务是否正常运行的最快方式：

{ "action": "getCurrentTime" }

要使用第二个 Google 账号操作，请参阅多账号。

多账号

每个域工具都接受 account 参数——即调用所操作的 Google 账号邮箱。 省略该参数时，调用会针对主账号执行。

{ "action": "search", "query": "is:unread", "account": "[email protected]" }
{ "action": "search", "query": "is:unread" }

这两次 gmail 调用读取的是两个不同的邮箱：第一次读取 [email protected]， 第二次读取当前的主账号。

通过 config 工具管理账号：

调用	效果
config(action="account_add")	在 stdio 中，返回一个可打开的 URL；在该页面完成 Google 授权后，即可添加一个账号。在 HTTP 中，返回需要在主机上运行的 workspace auth --user <namespace> 命令。
config(action="account_list")	查看已配置的账号以及哪个账号是主账号。
config(action="account_remove", account="<email>")	移除一个账号。
config(action="account_set_default", account="<email>")	将一个账号设为主账号。

第一个获授权的账号会成为主账号。移除主账号后，会将剩余账号中的一个提升为主账号；移除最后一个账号后，服务会恢复为等待设置状态。指定未配置的账号会报错并显示该账号名称——调用绝不会改为针对主账号执行，因为静默回退可能会操作错误的邮箱。

account_add 会根据传输方式选择流程。在 stdio 中，它会启动一个临时的回环授权服务器并返回 URL。在 HTTP 中，它不会提供授权服务；而是返回需要在主机上运行的 workspace auth --user <namespace> 命令。

value="primary" 仅适用于 stdio；远程调用方应使用 account_set_default 更改默认账号。

从早期的单账号版本升级

多账号支持推出之前的版本所存储的凭据，是一组扁平的令牌。此后的首次运行会将这组令牌迁移到多账号布局，并关联到该账号的邮箱。邮箱来自已存储的 id_token（如果存在）——这不需要网络连接，也是通常的情况。否则，服务会请求 Google 的 userinfo 端点，这需要网络连接，且令牌必须仍然有效或可刷新。

如果这两种方式都行不通，服务会报告自身处于等待设置状态，并打开浏览器 OAuth 流程，即使已存储的令牌可能仍然有效。完成授权后即可正常使用，而且不会丢弃任何内容：刚刚授权的账号会被存储并设为主账号，而旧令牌会以 (unidentified) 为键保留下来，不会被覆盖。此时 config(action="account_list") 会显示两个条目：

{ "accounts": ["(unidentified)", "[email protected]"], "primary": "[email protected]" }

任何调用都不会路由到 (unidentified)：只要仍有真实账号，它就不会被提升为主账号；除非显式指定，否则也不会有调用访问它。保留该条目是为了避免静默丢弃所有者身份无法确定的凭据。重新授权的账号正常运行后，即可移除该条目：

{ "action": "account_remove", "account": "(unidentified)" }

成功迁移后（通常如此），config(action="account_list") 会恰好显示一个账号，且该账号就是主账号。

Forms 作用域和重新授权

在 forms 工具推出之前，授权页面就已请求 Google Forms 作用域，因此无需再次授权即可使用。

此前已授权的账号也受支持，但采用另一种方式：对于此服务调用的所有 Forms 方法，Google 都接受 https://www.googleapis.com/auth/drive 代替 Forms 作用域，而完整的 drive 作用域从首次发布起就已显示在授权页面上。Google 不会扩大已签发令牌的权限，因此，如果授权既未涵盖 Forms 作用域也未涵盖 drive——用户可能会在授权页面拒绝单个受限作用域——首次调用 forms 时会返回 403（Request had insufficient authentication scopes）。只需使用 config(action="account_add") 重新授权该账号，并以同一账号登录；账号记录会原位替换，因此其他内容不会发生变化。

文档

完整文档请见 mcp.n24q02m.com/servers/better-workspace-mcp/：

• 设置 -- 插件安装、Docker stdio 和 Docker HTTP 方法
• 模式概览 -- stdio（默认）和 HTTP（多用户、Bearer 令牌）
• 多用户设置 -- 远程（HTTP 模式） 背后的按命名空间划分的凭据模型

每个工具也会在运行时提供自身文档：调用 help，即可查看任何工具的完整参考，包括每个操作所需的确切参数。

部署

此 MCP 服务没有托管端点。支持的方式是上文所述的 stdio 安装，以及自行部署的 HTTP 服务。

若要自行托管 HTTP 模式，请运行此代码库中的 compose overlay：

docker compose -f docker-compose.yml -f docker-compose.http.yml up

它会在本地构建 http 镜像，并仅在主机环回地址上发布。请通过 shell 或 .env 文件设置 GOOGLE_OAUTH_WEB_CLIENT_ID、GOOGLE_OAUTH_WEB_CLIENT_SECRET、CREDENTIAL_SECRET 和 WORKSPACE_USERS_FILE（参见环境）。用户文件会将每个 Bearer 令牌映射到一个用户命名空间；请在主机上使用 workspace auth --user <namespace> 添加账户。若要在本机之外使用，请在同一主机上将自有的 TLS 反向代理置于其前方。

每个版本还会向 Docker Hub 和 GHCR 发布多架构容器镜像；其默认阶段为 http 服务。

贡献

请参阅 CONTRIBUTING.md。

许可证

Apache-2.0 © n24q02m