Google Workspace

@mindstone/mcp-server-google-workspace

Google Workspace MCP 服务——Gmail、Calendar、Drive、Docs、Sheets、Slides、Contacts、Chat、Meet、Tasks、Forms、Comments 和账户诊断。

支持多个账户的 Google Workspace MCP。由宿主协调 OAuth（连接器既不运行回调服务，也不生成 OAuth URL），按账户原子化写入凭据，并通过结构化的 auth_required 交接，让宿主引导登录流程，而不是由服务处理。

状态

• 版本： 0.5.0 · npm：尚未发布
• 身份验证： OAuth（由宿主协调）(GOOGLE_CLIENT_SECRET)
• 工具： 124（Gmail、Calendar、Drive、Docs、Sheets、Slides、Contacts、Chat、Meet、Tasks、Forms、Comments、Account）
• 接口： cloud-api
• 机器可读： STATUS.json

此连接器基于 aaronsb/google-workspace-mcp，并在 package.json#attribution 中注明出处。

项目缘由

我们在 2026 年初移植此项目时，Google 尚未为 Workspace 功能推出官方 MCP 服务。当时的社区方案各自都解决了部分问题——我们以 Aaron Brown 的 aaronsb/google-workspace-mcp 作为起点。它覆盖了广泛的 Workspace API，但会在 OAuth 期间运行自己的浏览器回调服务，而我们的宿主应用本身已经具备该功能。我们将其分叉，以便 MCP 宿主能够全权处理 OAuth 流程（连接器会返回结构化的 auth_required 响应，而不是运行回调服务或计算 OAuth URL）；每个账户的令牌文件都会以原子方式写入，并设置严格的权限且拒绝符号链接；此外，每次发布前，连接器都会经过我们自己的安全审查。Google 的 Workspace MCP 此后已发布；我们仍会维护此项目，因为它集成了我们宿主的凭据文件布局、由宿主协调的 OAuth 交接流程，以及恢复指引契约。此项目现已成为在本仓库中独立维护的硬分叉——我们不会同步上游项目的变更。

交互示例

“查找 Alice 昨天发送的关于 Q3 规划的邮件会话，并回复‘谢谢，我今晚会读’。”

宿主调用的工具：

1. search_workspace_emails — 在 Gmail 中搜索 from:alice@... subject:"Q3 planning" newer_than:1d。
2. reply_to_workspace_email — 使用提供的正文回复返回的会话 ID。

响应（已删节）：

{
  "thread": {
    "id": "1928a...",
    "subject": "Q3 planning",
    "from": "[email protected]"
  },
  "reply": {
    "id": "1928b...",
    "labelIds": ["SENT"]
  }
}

要求

• Node.js 20+（engines.node 为 >=18，但构建和测试均在 20 和 22 上运行）
• npm
• 能够执行 Google OAuth 流程，并将 accounts.json 和每个账户的令牌文件写入磁盘，供连接器读取的宿主应用。

快速开始

安装并构建

cd <path-to-repo>/connectors/google-workspace
npm install
npm run build

npx（发布后）

npx -y @mindstone/mcp-server-google-workspace

本地

node dist/index.js

配置

此服务旨在与自行执行 Google OAuth 流程的宿主应用配合运行。宿主将凭据写入磁盘；此服务读取这些凭据。

必需的环境变量

变量	说明
GOOGLE_CLIENT_ID	Google OAuth 客户端 ID。
GOOGLE_CLIENT_SECRET	Google OAuth 客户端密钥。
ACCOUNTS_PATH	accounts.json 的路径（由宿主写入的已验证账户索引）。
CREDENTIALS_PATH	存放各账户 Google OAuth 令牌文件的目录。

可选环境变量

变量	默认值	描述
GOOGLE_WORKSPACE_REQUEST_TIMEOUT_MS	60000	Google API 出站请求超时时间，单位为毫秒（最大值为 300000，即 5 分钟）。

主机可注入 GOOGLE_WORKSPACE_DISABLE_REFRESH=1，使连接器返回 auth_required，而不是刷新令牌。此变量特意不作为面向用户的设置变量。

身份验证流程

authenticate_workspace_account 会返回结构化的 auth_required 响应：

{
  "status": "auth_required",
  "user_action": { "id": "google.connect_account" },
  "agent_action": {
    "instruction": "Connect Google Workspace to continue. The user will be redirected to Google's sign-in."
  },
  "setupToolName": "authenticate_workspace_account"
}

连接器不会运行回调服务器，也不会生成 OAuth URL。MCP 主机会计算 Google OAuth URL 并处理回调。主机将账户的令牌文件写入 CREDENTIALS_PATH/，并在 ACCOUNTS_PATH 中写入条目后，下一次工具调用即可成功。

主机配置示例

Claude Desktop / Cursor

{
  "mcpServers": {
    "GoogleWorkspace": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-google-workspace"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-google-oauth-client-id",
        "GOOGLE_CLIENT_SECRET": "your-google-oauth-client-secret",
        "ACCOUNTS_PATH": "/absolute/path/to/accounts.json",
        "CREDENTIALS_PATH": "/absolute/path/to/credentials"
      }
    }
  }
}

在主机写入 ${ACCOUNTS_PATH} 和对应账户的令牌文件到 ${CREDENTIALS_PATH}/ 之前，每次工具调用都会返回结构化的 auth_required 响应（参见上面的“身份验证流程”）。

本地开发（无需发布到 npm）

{
  "mcpServers": {
    "GoogleWorkspace": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/google-workspace/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-google-oauth-client-id",
        "GOOGLE_CLIENT_SECRET": "your-google-oauth-client-secret",
        "ACCOUNTS_PATH": "/absolute/path/to/accounts.json",
        "CREDENTIALS_PATH": "/absolute/path/to/credentials"
      }
    }
  }
}

工具（124 个）

完整列表位于 src/tools/definitions/ 下，也可在 tools-inventory.json 中查看。按领域分组：

领域	工具数	说明
Gmail	23	搜索、查看邮件会话、发送和撰写邮件；管理草稿、标签、标签筛选条件和附件；归档、移至垃圾箱、设置已读状态；以及设置、休假自动回复、发送身份别名和签名。
Calendar	9	查看当前时间、查询空闲时段、列出日历和事件、创建和更新事件、回复及删除事件。
Drive	15	列出、搜索、上传、下载、复制、移动、移至垃圾箱和恢复文件；管理文件夹、权限和修订版本；发现共享云端硬盘；以及查询活动（更改内容、时间和操作者）。
Docs	13	阅读、创建、追加、替换、查找和替换（整个文档或单个标签页）、在锚点处插入文本、查看标签页树、添加/重命名/移动/删除标签页、将一个标签页的内容复制到另一个标签页，以及批量更新。阅读、追加、替换和查找/替换可针对单个标签页（tab_id）；阅读也可覆盖所有标签页（all_tabs）。
Sheets	17	读取和写入区域、创建电子表格、管理工作表（添加、复制、重命名、重新排序、删除）、插入格式与相邻行或列相同的行或列、批量操作、查找和替换，以及格式设置。
Slides	7	阅读、创建、列出和获取幻灯片、批量更新、生成缩略图，以及提取 ID。
Labels	12	Gmail 标签的增删改查（CRUD）及筛选规则。
Contacts	4	列出、搜索、创建和更新联系人。
Chat	3	列出空间、列出空间中的消息，以及发送文本消息。
Meet	3	列出会议记录、列出文字稿，以及读取文字稿条目（发言者 + 文本）。
Comments	5	列出、创建、回复、解决和删除 Drive 评论。
Account	3	列出、验证和移除工作区账户。
Tasks	6	列出任务列表，以及列出、创建、更新、完成和删除任务。
Forms	4	只读访问表单及其回复。

共享云端硬盘

所有 Drive 文件、权限和评论工具都适用于共享云端硬盘中的文件（files.* 和 permissions.* 调用会传递 supportsAllDrives；Comments API 通过文件 ID 定位文件，且没有定义此类标志）。列表和搜索默认仅涵盖用户自己的语料库及与其共享的文件，因此用户有权访问但从未打开过的共享云端硬盘内容，默认情况下可能不会显示。要明确操作共享云端硬盘：

• 发现云端硬盘： list_shared_drives 会返回该账号可访问的共享云端硬盘（ID、名称、创建时间）。
• 指定一个云端硬盘： 将 options.driveId 传递给 list_drive_files / search_drive_files。只要设置了 driveId，连接器就会强制使用 corpora: 'drive'（Drive API 会拒绝其他组合），覆盖调用方提供的 corpora。
• 搜索全部内容： 不设置 driveId，并传递 options.corpora: 'allDrives'，即可通过一次查询搜索“我的云端硬盘”和所有共享云端硬盘。Google 建议仅将此选项用于有针对性的搜索；浏览内容时优先使用特定的 driveId。

Drive API 对共享云端硬盘文件的已知限制（此连接器无法解决）：

• 共享云端硬盘中的原生文件没有 owners[] ——所有权属于云端硬盘本身。归属文件时，可将 lastModifyingUser 和 createdTime 作为参考。
• Revisions API 不支持共享云端硬盘文件，因此 list_file_revisions / download_file_revision 仅适用于“我的云端硬盘”中的文件。

Docs 标签页

一个 Google Doc 可以包含多个标签页，并支持多层嵌套。每个标签页都有一个 ID，例如 t.abc123；list_workspace_document_tabs 会显示完整的树状结构，包括每个标签页的 ID、父级和位置。包含 ?tab=t.xxxx 的 Docs 链接指向一个标签页，而 t.xxxx 就是它的标签页 ID。

不指定 tab_id 时：

• read_workspace_document 会返回第一个标签页；如果文档包含多个标签页，还会附加一行说明标签页数量。传递 tab_id 可读取一个标签页，传递 all_tabs: true 可读取所有标签页，并以 ## Tab: 标题区分；所有标签页共用同一个 max_chars 限额（未能容纳的标签页会按 ID 列出）。
• append_to_workspace_document、replace_workspace_document 和 insert_workspace_document_text 会操作第一个标签页。工具调用不会沿用之前调用所用的标签页，因此，每次调用都应传递 tab_id，以确保操作其他标签页。
• find_and_replace_workspace_document 会替换所有标签页中的内容。传递 tab_id 可将操作限制在一个标签页内（其子标签页是单独的标签页，不会包含在内）。

对于读取、编辑、锚定插入、添加标签页时的 parent_tab_id 以及复制源，tab_id: "default" 表示第一个顶层标签页。删除、重命名、移动或覆盖标签页的工具需要真实的标签页 ID，并会拒绝 "default"。

管理标签页： add_workspace_document_tab、update_workspace_document_tab（重命名、重新排序或嵌套到另一个标签页下；API 无法将子标签页移回顶层）和 delete_workspace_document_tab。

• 整个文档中的标签页标题必须唯一，子标签页也包括在内；如果发生冲突，系统会拒绝操作，且不会进行任何更改。
• position 从 0 开始，在同级标签页中计数（0 = 第一个），表示移动后标签页所在的位置。列表输出中的数字从 1 开始。结果会报告文档实际显示的位置。
• 删除标签页时，其所有子标签页也会一并删除。如果标签页有子标签页，除非传递 delete_sub_tabs: true，否则删除操作会被拒绝。 在锚点处插入文本： insert_workspace_document_text 会在一个标签页中添加纯文本，而不会重写内容。anchor_text 必须在该标签页中、某个段落内恰好出现一次。position 可以是 after（默认值）、before（锚点之前），或 next_paragraph_start（锚点所在段落之后的段落开头）；这是在标题下的空项目符号中填入内容的方式。将锚点设在该位置正上方的那一行；除非传入 expect_empty_paragraph: false，否则该行所在的段落必须为空。换行符会新建段落，并沿用所在段落的标题或项目符号格式；插入的文本本身是纯文本（不会继承相邻内容的粗体或链接）。

复制标签页： copy_workspace_document_tab 会将一个标签页的内容复制到同一文档中的另一个标签页。

• 会复制：文本、标题和段落样式、字符样式和链接、项目符号和编号（映射为 Google Docs 的预设列表样式）、表格（单元格文本、列宽、单元格样式）、分页符和智能芯片。指向你无权打开的文件的智能芯片会变为带标题的链接；人员和日期芯片会变为相应文本。结果中会列出这两类内容。
• 不会复制：页眉和页脚、子标签页、图片和其他特殊元素（会在“不会复制”下列出；行内元素还会留下可见的 [placeholder]），以及表格单元格合并（单元格会以未合并状态复制；如果表格中的合并单元格无法复制，则会在写入任何内容之前拒绝操作）。
• 无法忠实复制的内容：指向被复制标签页内标题的链接仍会指向原标签页中的标题，因此重置后将无法解析。
• 选择目标：若要归档或复制标签页，请使用 new_tab_title。若要使用模板标签页原位重置标签页（保留其 ID、位置和子标签页），请将 target_tab_id 与 overwrite_existing: true 一起使用；这会先清空目标标签页。切勿为了替换标签页而将其删除：删除标签页也会删除其子标签页。
• 结果以一行 Verification: 开头，用于比较文本、标题类型、段落格式、项目符号、列表分组和表格形状与源内容是否一致。删除或重置源内容之前，请确认结果显示 passed，且“不会复制”一行没有列出任何你不能舍弃的内容：即使验证通过，也可能有浮动图片等内容未被复制。验证失败时，结果会以错误形式返回。
• 复制不是原子操作。如果中途停止，连接器会再次尝试删除新建的标签页，并在结果中说明是否成功（若未成功，则会指出需要删除的标签页）；现有目标标签页可能会被清空或只写入部分内容（可通过文档的版本历史恢复）。如果复制完成但验证发现差异，标签页会保留以供检查，结果会列出最先发现差异的几个位置。较长的标签页可能需要 10-60 秒。

示例：每周归档并重置一个虚构的“Acme weekly sync”文档，该文档包含一个实时标签页和一个 Template 标签页。业务规则（下次会议日期、要保留哪些行）由调用方决定：

1. 使用 list_workspace_document_tabs 获取当前和模板标签页 ID，然后通过 tab_id: <live tab id> 读取当前标签页。记下日期行和外出行，在进行任何更改之前保留这些内容。
2. 使用 copy_workspace_document_tab，参数为 source_tab_id: <live tab id>、new_tab_title: "2031-10-13"、new_tab_parent_id: <live tab id> 和 new_tab_position: 0，将其存档为第一个子标签页。
3. 除非结果显示 Verification: passed，且其 Not copied 行没有列出存档无法缺少的任何内容，否则请停止。
4. 使用 copy_workspace_document_tab，参数为 source_tab_id: <Template tab id>、target_tab_id: <live tab id> 和 overwrite_existing: true，在原位置重置当前标签页。
5. 使用 find_and_replace_workspace_document 替换日期占位符，并指定 tab_id: <live tab id>（不指定的话，模板中的占位符也会被更改），并检查结果是否显示 Replaced 1。
6. 使用 insert_workspace_document_text 插入保留的外出行，并指定 tab_id: <live tab id>（不指定的话，文本会插入第一个标签页，这可能是模板），并设置 position: "next_paragraph_start"，锚定在空项目符号正上方的那一行。

休假自动回复

update_workspace_vacation_responder 会与现有设置合并（Gmail API 否则会替换整个资源）：省略的主题/正文会保留，现有 HTML 正文仍保持 HTML 格式，省略 end_time 时会保留待执行的计划结束时间。若要移除计划结束时间并让自动回复持续生效，请传入 clear_end_time: true（不可与 end_time 同时使用）。重新启用时不会沿用已过期的结束时间。

安全说明

• 令牌和账户写入采用临时文件加重命名、限制性权限、fsync，并拒绝符号链接。
• 主机可禁用令牌刷新，以便由单一授权方负责刷新令牌轮换（GOOGLE_WORKSPACE_DISABLE_REFRESH=1）。
• 可由用户恢复的失败会返回与主机无关的恢复指引，其中包含 action_required 和 next_step 字段。
• 已移除随附的回调服务器；OAuth URL 和回调处理仍由 MCP 主机负责。
• 附件文件名经过清理，可防止通过伪造的 upload_workspace_attachment 文件名参数实施路径遍历。
• <untrusted-content> 信封适用于 Contacts、Calendar、Comments、Forms、Tasks 和 JSON 返回路径。

许可证

FSL-1.1-MIT — Functional Source License，Version 1.1，未来许可证为 MIT。该软件将于 2030-04-08 转为 MIT 许可证。