Google Workspace

Google Workspace MCP 服务

通过 AI 助手，一次搜索、阅读和整理多个 Google 账号的邮件、日历、Drive 文件、Docs、Sheets、 Slides、Google Tasks、联系人和 Meet 转录稿。它可以撰写草稿、添加标签、创建过滤器、事件、 任务、文件、文档、评论和共享设置。没有任何操作会涉及 money，也不会永久删除邮件或文件： Gmail 和 Drive 会将内容保留在垃圾箱中 30 天。

邮件会一直保留为草稿，直到你说发送。 发送邮件、共享文件和发布修订版都是会告知助手先等你明确同意的 write 工具。服务本身不会询问你；客户端可以在每次调用前询问。设置 MCP_MAX_ACCESS=read 可将服务设为只读。

你需要 一个或多个 Google 账号、自己的 Google Cloud 项目及其桌面应用 OAuth 客户端（分步说明）， 以及一个浏览器，用于为每个账号一次性批准每款产品。处于 Testing 状态的应用，其授权会在七天后过期。Workspace 目录、 Meet 转录稿和智能笔记，以及专注时间和不在办公室事件，都需要 Google Workspace 账号。

你可以这样提问

• “查看我两个账号本周的日历，有什么安排冲突吗？”
• “下周找一个和 Ana Popescu 都有空的 45 分钟时段，优先选上午。”
• “把 9 月收到的所有 PDF 都从我的工作邮箱保存为附件。”
• “起草一封回复 Ana 最新邮件的邮件，告诉她周四 10 点可以。我会自己发送。”
• “把这些发票添加到 Invoices 表格中，并更新发票编号已存在的行。”
• “昨天和 Client SRL 的通话中我们决定了什么？给我读一下转录稿。”

安装

使用 Claude Code：

claude mcp add google -e GOOGLE_OAUTH_CLIENT_FILE="<path to OAuth client file>" -e GMAIL_ADDRESSES="<Accounts and their addresses>" -e GMAIL_MODIFY_ACCOUNTS="<Where Gmail grants are kept>" -- npx -y @foreverworks/mcp-google

Claude Desktop（Settings、Developer、Edit Config）和大多数其他客户端都以 JSON 格式读取相同的命令：

{
  "mcpServers": {
    "google": {
      "command": "npx",
      "args": ["-y", "@foreverworks/mcp-google"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_FILE": "<path to OAuth client file>",
        "GMAIL_ADDRESSES": "<Accounts and their addresses>",
        "GMAIL_MODIFY_ACCOUNTS": "<Where Gmail grants are kept>"
      }
    }
  }
}

每个客户端都会在 Node 22.19 或更高版本上运行已发布的软件包。VS Code 和 Claude Desktop bundle 添加服务时会询问每项设置；可选项可以留空。Cursor 则从环境中读取各项设置（例如 ${env:GOOGLE_OAUTH_CLIENT_FILE}），因此请在启动 Cursor 前设置好这些变量。以上命令只设置必需项；其余设置请参阅配置。

从克隆版本安装

git clone https://github.com/foreverworks/mcps.git && cd mcps
npm ci && npm run build
claude mcp add google -e GOOGLE_OAUTH_CLIENT_FILE="<path to OAuth client file>" -e GMAIL_ADDRESSES="<Accounts and their addresses>" -e GMAIL_MODIFY_ACCOUNTS="<Where Gmail grants are kept>" -- node "$PWD/servers/google/dist/index.js"

在 JSON 配置中，命令为 node，其唯一参数是 servers/google/dist/index.js 的完整路径。若要让多个客户端通过 HTTP 共用一个运行中的实例，请参阅 docs/deploying.md。

通过 HTTP（MCP_HTTP_PORT）运行时，一个进程会为每个会话提供服务，并为每个授权许可缓存一个令牌。

配置

服务启动时未设置任何配置：尚未完成设置的产品会返回 config 错误，并指出需要设置的内容。四个变量适用于大多数配置。

变量	必需	含义
GOOGLE_OAUTH_CLIENT_FILE	用于授权	来自 Google Cloud 控制台的 OAuth 客户端 JSON 文件（桌面应用客户端）。新授权会通过它完成。如果没有此文件，授权会借用该账号已有某个凭据文件中的客户端。
GMAIL_ADDRESSES	用于授权	label=address,...：每个账号标签在所有产品中代表的 Google 地址。若授权时使用了其他身份，则会被拒绝；health 会检查 Gmail 授权是否与之匹配。
GMAIL_MODIFY_ACCOUNTS	用于 Gmail	label=path,...：存放各邮箱自身 gmail.modify 授权的位置。begin_consent 会将其写入该位置。
CALENDAR_TIME_ZONE	否	没有时区偏移的时间所采用的 IANA 时区，也是工作时间默认采用的时区；默认为进程的时区（TZ）。

标签由小写字母、数字和连字符组成（personal、work、client-a），在所有产品中代表一个 Google 身份。服务写入的所有内容（令牌缓存、授权、等待中的授权、下载内容）都会存放在 GOOGLE_STATE_DIR 下：默认使用 systemd 的 STATE_DIRECTORY，否则使用 $XDG_STATE_HOME/mcps/google（~/.local/state/mcps/google），除非下方的某个变量更改了某个产品对应的目录。

其他所有变量（均为可选）

| 变量 | 含义 | |---|---| | `GMAIL_ACCOUNTS` | `label=path,...`：每个邮箱各自的只读（`gmail.readonly`）授权，由其他程序生成，例如邮件同步程序。如果某个邮箱的 `gmail.modify` 授权文件不存在，就会使用此授权：可以读取，但所有写入操作都会被拒绝。 | | `GMAIL_DEFAULT_ACCOUNT` | 未指定邮箱时，单邮箱读取操作所用的邮箱；默认使用列表中的第一个。 | | `GMAIL_STATE_DIR` | Gmail 的令牌缓存，位于 `//`；默认为 `/gmail/state`。 | | `GMAIL_ATTACHMENTS_DIR` | 附件的保存位置，位于 `//`；默认保存在每个邮箱状态文件夹中的 `attachments/`。 | | `GMAIL_TIME_ZONE` | 回复中“On `` ... wrote:”这一行和转发邮件的 Date 行所使用的时区，与 Gmail 在阅读者的时区中显示的格式一致；默认使用 `CALENDAR_TIME_ZONE`，否则使用进程时区。 | | `CALENDAR_ROOT` | 日历授权，位于 `//credentials.json`（通过授权流程写入）；默认为 `/calendar`。 | | `CALENDAR_DEFAULT_ACCOUNT` | 单账号日历读取操作所用的账号；默认按名称排序后的第一个账号。 | | `DRIVE_CREDENTIALS` | Drive 的单个授权（通过授权流程写入）；默认为 `/drive/credentials.json`。 | | `DRIVE_STATE_DIR` | Drive 的令牌缓存；默认为 `/drive/state`。 | | `DRIVE_DOWNLOADS_DIR` | `download_file` 和 `download_revision` 的保存位置；默认为 `/drive/downloads`。 | | `DRIVE_MIRROR_ROOT` | 服务可读取的 My Drive 本地副本：`upload_file` 也会从此处获取文件，并将每个文件发送到其映射的文件夹。 | | `DRIVE_RCLONE_CONF` | rclone 配置；其中远程服务的授权会由 Drive 临时使用，直到 Drive 获得自己的授权。该远程服务必须携带自己的 `client_id` 和 `client_secret`，因为无法在此处刷新 rclone 内置客户端。未设置：不使用 rclone。 | | `DRIVE_RCLONE_REMOTE` | 该远程服务的名称；默认为 `gdrive`。 | | `GOOGLE_EDITORS_ROOT` | Docs、Sheets 和 Slides 的授权，位于 `//credentials.json`；默认为 `/editors`。 | | `GOOGLE_EDITORS_STATE_DIR` | Docs、Sheets 和 Slides 的令牌缓存，位于 `//`，用于授权必须保持只读的情况；默认为 `//state`。 | | `GOOGLE_EDITORS_DRIVE_ACCOUNT` | Docs、Sheets 和 Slides 使用 Drive 授权的账号标签。未设置：都不使用该授权。 | | `GOOGLE_EDITORS_DEFAULT_ACCOUNT` | 未指定账号时，Docs、Sheets 或 Slides 读取操作所用的账号；默认使用获得 Drive 授权的账号，否则使用第一个账号。 | | `TASKS_ROOT` | Google Tasks 授权，位于 `//credentials.json`；默认为 `/tasks`。 | | `CONTACTS_ROOT` | 联系人和通讯录的授权，路径格式相同；默认为 `/contacts`。 | | `MEET_ROOT` | Meet 记录的授权，路径格式相同；默认为 `/meet`。 | | `GOOGLE_CONSENT_REDIRECT_URI` | 授权流程重定向到的环回地址；默认为 `http://localhost:8123/`。 | | `GOOGLE_STATE_DIR` | 上述所有目录的根目录。 | | `GOOGLE_TOOLSETS` | 服务加载工具的产品，以逗号分隔；默认加载所有产品（[工具集](#toolsets)）。 |

所有服务共用的变量（MCP_HTTP_PORT、MCP_MAX_ACCESS、 MCP_FILE_ROOTS、MCP_FILE_SCRIPT 等）见 docs/configuration.md。

工具集

服务器提供给客户端的每个工具定义都会随客户端发出的每个请求一同传输， 因此，只需要邮件和日历的客户端仍需为云端硬盘、文档、表格及其他内容付出 同样的开销。GOOGLE_TOOLSETS 用逗号分隔的产品名称指定要加载的产品，方式 与 GitHub 的 MCP 服务采用 GITHUB_TOOLSETS 相同。未加载产品的工具完全不 会出现：不在工具列表中，不在服务器的说明中，也不在 list_accounts 或 health 中。未设置、为空或设为 all 时，会加载所有产品， 与之前相同。

工具集	加载内容
gmail	邮件：搜索、读取、草稿、发送、标签、过滤器和附件。
calendar	活动、空闲/忙碌状态、查找时间以及回复邀请。
drive	云端硬盘中的文件和文件夹：路径、变更、上传和下载。
docs	Google 文档、简单编辑和完整 API，以及 editors_api_reference。
sheets	Google 表格、行和范围以及完整 API，以及 editors_api_reference。
slides	Google 幻灯片、根据大纲创建的演示文稿以及完整 API，以及 editors_api_reference。
collaboration	对任何云端硬盘文件的评论、共享和修订。
tasks	Google Tasks。
contacts	find_people：联系人、已保存的地址和 Workspace 目录。
meet	Meet 的会议、文字记录和智能笔记。

list_accounts、health、begin_consent 和 complete_consent 始终会加载：其他 每个工具都会采用 list_accounts 指定的标签，每项补救措施都会指向 health，而授权是授予任何权限的方式，包括已加载产品所依赖的权限（Meet 通过日历授权读取日历活动）。如果名称不是工具集之一，服务器会在启动时停止， 并显示可用工具集列表。使用 scripts/measure-tokens.ts 在 2026-10-23 测得（GPT-4 分词器）：启用所有工具集时， 工具列表包含 115 个工具，约 84,800 个 token（不含产品图标时为 39,200 个，客户端可能 不会向模型显示这些图标）；启用 gmail,calendar 时包含 43 个工具，共 35,600 个 token（16,100 个）；启用 drive,docs,sheets 时包含 46 个工具，共 32,400 个 token（15,200 个）。

若要仅加载邮件和日历，可在 Claude Code 中使用：

claude mcp add google -e GOOGLE_TOOLSETS=gmail,calendar -e GOOGLE_OAUTH_CLIENT_FILE="<path to OAuth client file>" -e GMAIL_ADDRESSES="<Accounts and their addresses>" -e GMAIL_MODIFY_ACCOUNTS="<Where Gmail grants are kept>" -- npx -y @foreverworks/mcp-google

或在 Claude Desktop 的配置中使用：

{
  "mcpServers": {
    "google": {
      "command": "npx",
      "args": ["-y", "@foreverworks/mcp-google"],
      "env": {
        "GOOGLE_TOOLSETS": "gmail,calendar",
        "GOOGLE_OAUTH_CLIENT_FILE": "/path/to/oauth-client.json",
        "GMAIL_ADDRESSES": "[email protected],[email protected]",
        "GMAIL_MODIFY_ACCOUNTS": "personal=/path/to/grants/gmail-personal.json,work=/path/to/grants/gmail-work.json"
      }
    }
  }
}

工具集会移除工具；MCP_MAX_ACCESS=read 则保留所有工具的列表，但会拒绝写入操作。无论 GOOGLE_TOOLSETS 如何设置，Shell 的 --health 都会检查每个产品；指定产品名称可缩小检查范围。

获取 OAuth 客户端

你自己的一个 OAuth 客户端即可供所有账号和产品使用。

1. 在 Google Cloud 控制台 中，为此服务创建一个项目。

2. 在 APIs & Services、Library 下，启用你将使用的产品对应的 API：Gmail API、Google Calendar API、Google Drive API、Google Docs API、Google Sheets API、Google Slides API、Google Tasks API、People API（联系人和目录）以及 Google Meet REST API。

3. 打开 Google Auth Platform。在 Branding 下，为应用命名并填写你的电子邮件地址。在 Audience 下，选择允许哪些人使用，然后将每个账号添加为测试用户，或发布应用：Google 会在应用处于 Testing 状态七天后，使其刷新令牌过期。对于你自己的账号，已发布的应用可以保持未验证状态；在授权时，继续通过 Google 的警告页面。

4. 在 Data Access 下，添加你将使用的产品对应的范围（每个范围由 https://www.googleapis.com/auth/ 加上下面的名称组成）：

   产品	范围
   gmail	gmail.modify，以及用于过滤器的 gmail.settings.basic
   calendar	calendar.events、calendar.calendarlist.readonly、calendar.events.freebusy
   drive	drive
   editors（Docs、Sheets、Slides）	documents、spreadsheets、presentations、drive.file
   tasks	tasks
   contacts	contacts.readonly、contacts.other.readonly，以及 directory.readonly（可选：只有 Workspace 账号才有目录）
   meet	meetings.space.readonly

   每次授权也会请求 userinfo.email，以便服务检查是谁批准了授权。

5. 在 Clients 下，选择 Create client，将应用类型设为 Desktop app，然后下载其 JSON 文件（其中的 installed 块包含 client_id 和 client_secret）。请妥善保管此文件，并将 GOOGLE_OAUTH_CLIENT_FILE 指向该文件。

6. 为你的账号命名；对于 Gmail，还要指定每个邮箱的授权归属：

   [email protected],[email protected]
   GMAIL_MODIFY_ACCOUNTS=personal=/path/to/grants/gmail-personal.json,work=/path/to/grants/gmail-work.json
   

   在你的客户端中将它们添加到服务配置，然后重启服务。

首次运行

每个产品都需要为每个账号授予一次授权，在浏览器中完成。

1. 请助手调用 list_accounts：查看每个产品已知的标签（邮箱来自 GMAIL_MODIFY_ACCOUNTS；其他产品则是已获授权的账号）。
2. 请它开始授权，例如：“对 calendar、账号 work 调用 begin_consent”。产品可以是 gmail、calendar、drive、editors、tasks、contacts 或 meet。
3. 打开它返回的 URL，使用指定的地址登录，并勾选每个方框。支持 MCP URL 引导的客户端会直接为你显示该页面。
4. 随后浏览器会按预期无法加载 http://localhost:8123/?state=...&code=...：那里没有服务在监听。请在 15 分钟内从地址栏复制完整地址，并交给助手调用 complete_consent。产品会在下一次调用时使用该授权。
5. 为每个产品和账号重复上述步骤。Drive 只有一个授权：只需授权一次 drive，选择 Drive 工具应访问的账号。该账号的 Docs、Sheets 和 Slides 可以共用此授权（GOOGLE_EDITORS_DRIVE_ACCOUNT=personal）；其他每个账号都要为 editors 单独授权。
6. 请助手调用 health。每项授权都应以你指定的地址刷新，并包含你勾选的范围；它检查的每个 API 都应正常响应。

在 shell 中运行 node dist/index.js --health [gmail|calendar|drive|editors|tasks|contacts|meet]，会为每个账号和授权打印一行，并以状态最差一行的代码退出，适用于定时任务。

工具

读取不会更改你的任何账户（下载工具会保存本地副本）；写入会更改其中一个账户。设置 GOOGLE_TOOLSETS 后，只有已加载工具集中的表格适用；账户和授权工具始终可用。

除 Drive（Drive 只有一个授权）、list_accounts、complete_consent 和 editors_api_reference 外，每个工具都需要传入 account，即 list_accounts 返回的标签。适用于跨账户读取的工具（search_threads、agenda、free_busy、find_time、list_calendars、list_tasks、list_task_lists、find_people 和 health）在未指定账户时会读取所有账户；其他读取工具使用对应产品的默认账户。写入没有默认账户，因为以错误身份创建的邮件或事件会以该身份发出。

账户和授权

工具	访问权限	功能
list_accounts	读取	各产品可访问的账户、默认账户，以及每个账户使用的授权。请从这里开始。
health	读取	按产品和账户显示：授权是否会刷新、解析到的地址、Google 授予的权限范围，以及 Docs、Sheets、Slides、Tasks、联系人和 Meet 的 API 是否已启用。
begin_consent	写入	授予某个产品访问某个账户权限的 URL；在浏览器中打开，并以指定地址批准。
complete_consent	写入	完成授权流程：使用批准后重定向到的 URL 检查授权，并将其保存到产品读取的位置。

Gmail

工具	访问权限	功能
search_threads	读取	使用 Gmail 查询语法，同时搜索所有邮箱，每条结果都会标注其账户。
get_thread / get_message	读取	获取邮件会话或邮件，包含正文和附件列表（detail：metadata、text、raw_html）。
get_messages	读取	单次调用获取一个邮箱中最多 25 封邮件，按给定顺序返回；无法读取的邮件会在原位置返回，并标记为 partial，其余邮件仍会返回。
get_attachment	读取	将一个附件保存到附件文件夹，并返回其大小和 sha256。
harvest_attachments	读取	单次调用保存搜索匹配的所有附件，并提供数量以供核对。
list_history	读取	获取自 historyId 之后添加的邮件：增量同步，无需再次搜索。
list_labels	读取	系统标签和用户标签。
sender_breakdown	读取	按域名列出搜索匹配的邮件会话来自哪些发件人，按数量从多到少排序。
list_filters	读取	列出过滤器及其条件对应的搜索内容。
get_draft / list_drafts	读取	获取草稿，每封草稿都附有 Gmail 网页链接。
create_draft / update_draft / delete_draft	写入	草稿：任何已指定收件人的邮件都默认保存为草稿。
reply / forward	写入	为所有相关方创建邮件会话；除非 send 为 true，否则保存为草稿。
send_draft / send_message	写入	发送。仅在用户明确要求发送该邮件时使用。
modify_labels / modify_labels_matching	写入	归档、标记为已读、加星标、归类：修改指定邮件会话的标签，或修改搜索匹配的所有邮件会话的标签（默认先试运行）。
create_label / update_label / delete_label	写入	用户标签；不允许操作系统标签。
create_filter / delete_filter	写入	创建或删除用于设置标签的过滤器（不转发）；将邮件发送到 TRASH 或 SPAM 的过滤器需要 discard。
trash / untrash / mark_spam / unmark_spam	写入	操作邮件会话或邮件；无法永久删除。

日历

工具	访问权限	功能
agenda	读取	按时间顺序列出所有账号中的活动，以及活动之间的冲突和尚未回复的邀请；启用 include_tasks 后，也会列出这些日期到期的任务。
list_calendars	读取	列出每个账号可见的所有日历，以及 agenda 是否会读取这些日历。
get_event	读取	完整查看一个活动：描述、嘉宾及其回复、提醒和会议链接。
free_busy	读取	合并列出所有账号中的忙碌时段，以及其他人的忙碌时段（attendees）；无法读取的内容也会列出。
find_time	读取	在工作时间内（默认周一至周五 09:00 至 18:00），按指定时长查找空闲时段，并考虑提前通知时间和缓冲时间。
create_event / update_event / delete_event	写入	创建、更新或删除活动；可按需生成新的 Meet 链接，也可设置专注时间或外出时段。除非 send_updates 指明，否则不会向任何人发送邮件；只有设置 scope: "series" 才会修改整个系列。
respond_to_invite	写入	接受、拒绝或暂定回复邀请；只更改你自己的回复。

Drive

工具	访问权限	功能
resolve_path / path_of	读取	将路径解析为其对应的 ID（如果有两个路径对应同一 ID，则返回这些 ID），或反向解析。
list_folder / find_files / describe_file	读取	列出文件夹内容、搜索整个 Drive，或查看单个文件的元数据。
read_doc	读取	将 Doc、Sheet 或演示文稿导出为文本、Markdown 或 HTML。
start_drive_cursor / drive_changes	读取	通过一次调用返回自某个游标以来的变更，仅返回增量内容。
download_file	读取	将文件保存到下载文件夹，并先与 Drive 的校验和进行核对（Google 文件会先导出）。
upload_file	写入	按字节原样将文件上传到 Drive，并与 Drive 存储的内容进行核对；上传文件若已损坏，会被撤回。启用 convert 后，.docx、.xlsx 或 .pptx（及其旧格式或 .csv）会转换为 Google Doc、Sheet 或演示文稿。
copy_file / move_file / rename_file	写入	复制、移动（支持试运行，列出每一项冲突）和重命名文件，也适用于 Docs。
create_folder	写入	创建文件夹及其上级路径中所有尚不存在的文件夹。
trash_file / untrash_file	写入	将文件移至 Drive 垃圾箱或从中恢复；文件可在 30 天内恢复，无法永久删除。

评论、共享和修订版本

适用于任何 Drive 文件（Doc、Sheet、演示文稿或 PDF），并以 Docs、Sheets 和 Slides 账号的身份操作。

工具	访问权限	功能
list_comments	读取	列出评论串、回复、引用文本和解决状态；统计未解决和已解决的评论。
add_comment / reply_to_comment	写入	新建评论串，或回复并解决或重新打开评论串。
edit_comment / delete_comment	写入	修改或删除评论或回复的文本。
list_permissions	读取	列出谁以何种方式拥有访问权限，并简要显示链接共享设置。
share_file / update_permission / remove_permission	写入	授予、更改或撤销个人、群组、网域或任何持有链接者的访问权限；只有在明确要求时才会发送 Drive 邮件。仅在用户明确同意后操作。
list_revisions	读取	列出文件的修订版本：修改者、时间，以及旧版本可保存为的格式。
download_revision	读取	将某个修订版本下载到下载文件夹，并与其 MD5 值核对；Google 文件则会导出。
update_revision	写入	永久保留某个修订版本，或将 Google 文件的修订版本发布到网络上（仅在用户明确同意后操作）。

Docs、Sheets 和 Slides：API 参考

工具	访问权限	功能
editors_api_reference	读取	根据 API 自身的架构，说明任何 Docs、Sheets 或 Slides 请求种类或类型所需的参数；不指定名称时，返回所有请求种类。

文档

工具	访问权限	功能
read_document	读取	以 Markdown 格式读取任意标签页中的文档，并返回其章节索引和 revisionId。
edit_document_section	写入	在任意标签页中，将一个标题下的所有内容替换为 Markdown，并固定到读取时的修订版本。
append_to_document	写入	在任意标签页的最后一个段落后添加 Markdown。
create_document	写入	在文件夹中根据 Markdown 创建新文档。
get_document	读取	获取包含所有索引的结构：标签页、带样式和文本片段的段落、逐个单元格的表格、对象；还可按需获取页眉、页脚、脚注、列表、命名范围和样式；也可通过字段掩码获取原始 JSON。
find_in_document	读取	查找文本或正则表达式出现的所有位置，并以请求可用的范围形式返回，同时提供对应的修订版本。
batch_update_document	写入	在一个原子批处理中执行任意 Docs API 请求，先根据架构进行检查；凡是请求中指定了索引，都会固定到相应修订版本；本地图片通过 images 提供。

表格

工具	访问权限	功能
list_sheets	读取	标题、区域设置、时区，以及每个工作表的 ID、大小和冻结行数。
read_rows	读取	以表头为键返回行对象，并提供类型化数据：数字、ISO 日期、精确到原始小数位的货币值。
read_sheet_cells	读取	为没有表头的工作表读取稀疏单元格，包括公式、链接、智能芯片和备注。
append_rows / upsert_rows	写入	在末尾添加行，或按键列匹配并更新行；所有操作在一个原子批处理中完成。
write_range	写入	将值或公式写入指定工作表的 A1 范围；返回单元格原先的内容。
format_range	写入	设置数字格式、文本样式、颜色、边框、冻结行和列。
link_sheet_cells	写入	为已有文本单元格添加超链接；先检查文本是否与预期一致。
add_chart	写入	根据数据范围创建图表。
create_spreadsheet	写入	在文件夹中创建新的表格，并包含命名工作表和加粗、冻结的表头行。
get_spreadsheet	读取	获取包含所有 ID 的结构：工作表、合并单元格、条件格式、筛选器、受保护范围和带状范围、图表、切片器、表格、分组、命名范围（以 A1 表示）；也可通过范围和字段掩码获取包含网格数据的原始 JSON。
get_values	读取	获取多个范围的值（或数据筛选器选定的单元格），可采用格式化、未格式化或公式形式。
update_values / clear_values	写入	在一次调用中向多个范围或数据筛选器写入值（原始值或类型化值），或清空内容但保留格式。
append_values	写入	在 Sheets 根据范围找到的表格后添加行。
batch_update_spreadsheet	写入	在一个原子批处理中执行任意 Sheets API 请求，先根据架构进行检查；凡是接受 GridRange、GridCoordinate 或 DimensionRange 的位置，均可使用 A1 表示法。
copy_sheet_to	写入	将一个工作表复制到另一个表格或同一表格中。
search_developer_metadata	读取	按 ID 或数据筛选器搜索开发者元数据，并以 A1 表示每个标签的附加位置。

幻灯片

工具	访问权限	功能
list_layouts	读取	演示文稿的布局及每个布局的占位符。
read_deck	读取	每张幻灯片的布局、标题、其他文本和演讲者备注。
get_thumbnails	读取	每张幻灯片对应一个 PNG URL（约半小时后过期）。
create_deck_from_outline	写入	将模板复制到新的演示文稿中，每条大纲对应一张幻灯片，并先检查模板。
fill_placeholders	写入	替换演示文稿中所有 {{tag}}，并统计每种标记的数量。
get_presentation	读取	返回包含每个对象 ID 的结构：每张幻灯片的元素及其大小、变换和精确文本，以及备注的形状；也可通过字段掩码获取原始 JSON。
batch_update_presentation	写入	在一个原子批次中执行任意 Slides API 请求，先根据架构进行检查；可选择固定到某个修订版本；通过 images 使用本地图片。
create_presentation	写入	在文件夹中创建空白演示文稿，以便使用 batch_update_presentation 进行构建。

任务

工具	访问权限	功能
list_task_lists	读取	列出每个账号的所有 Google Tasks 清单，并标记默认清单。
list_tasks	读取	列出所有账号和清单中的任务；默认列出未完成的任务，也可指定两个日期之间的到期任务。
create_task / create_task_list	写入	创建任务（标题、备注、到期日期，可设为子任务或排在同级任务之后），或创建清单。
update_task / complete_task	写入	修改任务的标题、备注或到期日期；将任务标记为已完成，或重新设为未完成。只发送有变化的内容，因此重复执行不会产生变化。
move_task	写入	将任务移到另一个任务之下、排在同级任务之后，或移入同一账号的另一个清单。

联系人

工具	访问权限	功能
find_people	读取	按姓名跨所有账号查找联系人的地址，包括各账号的联系人、Gmail 保存的地址和 Workspace 目录，并将结果合并为每个人一条记录。

Meet

工具	访问权限	功能
list_meetings	读取	列出日历活动、Meet 链接或最近几天内的会议，并提供每场会议的转录稿、智能备注和录音。
get_transcript	读取	以逐行形式提供转录稿，注明发言人、发言内容和发言时间。

故障排查

失败时会返回 {"error": {"kind", "message", "remedy"}}，其中 remedy 会说明下一步该做什么。

config：“credentials at ... are missing or unparseable”、“Drive has no grant”或“no calendar grant for "work"”（其他产品也同理）。为该账号运行相应产品的授权（首次运行）；消息会列出已获得授权的账号。

config：“no address is known for "work"”或“"work" is not a mailbox here”。 在 GMAIL_ADDRESSES 中添加 work=<address>，或在 GMAIL_MODIFY_ACCOUNTS 中添加 work=<path>。“no OAuth client is known”表示未设置 GOOGLE_OAUTH_CLIENT_FILE。

input：“no consent is waiting for that state”。 授权在 15 分钟后过期、已完成，或是由状态目录不同的另一份服务副本发起的。请重新开始；每个授权 URL 只能使用一次。

授权时出现 auth 错误，代码为 wrong_account 或 insufficient_scope。 你使用了其他邮箱地址进行授权，或漏选了某个复选框；没有保存任何内容。请使用指定的邮箱地址重新开始，并勾选所有复选框。之后调用时出现 insufficient_scope，表示授权范围不包含该调用所需的权限（过滤器需要 gmail.settings.basic）：请重新授权该产品。

出现 auth 错误，代码为 readonly_grant。 该邮箱使用的是来自 GMAIL_ACCOUNTS 的只读授权，因此在发出任何请求前就会拒绝写入操作。请为其授权 gmail。

出现 auth 错误，代码为 invalid_grant。 刷新令牌已过期或被撤销。请重新授权该产品；如果应用处于 Testing 状态，请发布应用以停止每周过期。来自 GMAIL_ACCOUNTS 的只读授权会由创建它的机制续期。deleted_client 表示 OAuth 客户端本身已从 Cloud 控制台中删除。

api 的原因是 SERVICE_DISABLED 或 accessNotConfigured。 在授权所用 OAuth 客户端所属的 Cloud 项目中，启用 remedy 指出的 API。

api 对某个文件返回状态码 403。 该账号无法打开或更改该文件：请检查是否已将文件共享给该账号。如果只使用 editors 范围，Drive 允许客户端仅复制其创建或打开过的文件，因此 create_deck_from_outline 无法复制手动创建的模板；请使用该账号的 Drive 授权运行（GOOGLE_EDITORS_DRIVE_ACCOUNT）。

api 的原因是 outcome_unknown。 写入失败时，请求可能已到达 Google（连接中断或出现 5xx），因此不会重试。请先检查（已发送邮件或草稿、agenda、list_tasks、read_document、read_rows、read_deck），仅当内容不存在时才重试。

api 的原因是 stale_revision。 文档在读取后发生了更改：请重新读取并重做编辑。

api 的 list_history 返回状态码 404。 Gmail 已使该 historyId 过期：请使用 search_threads 重新搜索，并从 health 获取新的锚点。

quota。 即使经过每次重试，仍触及 Google 的每分钟配额限制。请等待一分钟。

ambiguous，且带有 candidates。 有两个 Drive 对象与该路径匹配。请使用 file_id 再次调用，并指定列出的其中一个 ID。

工作原理

账号与授权

• 每个产品和账号对应一项授权，各自拥有独立的令牌缓存，且仅包含该产品的作用域：Tasks 授权无法读取邮件，Calendar 令牌也永远不会用于 Gmail。
• 授权通过查找发现，而非列出：Calendar、Docs、Sheets 和 Slides、Tasks、联系人和 Meet 会在每次调用时查找 <root>/<label>/credentials.json，因此无需重启即可使用新授权。
• 凭据采用 google.oauth2 JSON 格式（refresh_token、client_id、client_secret、token_uri、scopes、account）。服务器会忽略已存储的访问令牌，并在锁定状态下刷新，因此共享同一状态目录的副本只会刷新一次。
• 文件声明作用域；Google 授予作用域。 health 会从 Google 的 tokeninfo 中读取每项授权的实际作用域、客户端和地址；如果只读 Gmail 授权增加了写入作用域，就会失败。
• 授权同意使用 PKCE（S256）和 prompt=consent（每次都会获取刷新令牌），并将账号地址设为 login_hint。如果授权是用其他地址批准的、缺少必需作用域，或没有刷新令牌，就会被拒绝且不会写入任何内容；可选作用域可以不授权。等待中的授权和授权文件会以 0600 权限写入，替换的授权会保留为 .bak，且结果中不会出现令牌。

Gmail

• 发送操作绝不会盲目重试：只有能证明 Gmail 未执行操作的响应（429、速率限制导致的 403、刷新前的 401）才会重试。发送所依赖的所有内容都会提前读取，因此已发送的邮件绝不会被报告为失败。
• 回复的格式与 Gmail 自身一致：保留原邮件的标记、Gmail 风格的引用说明和内嵌图片，让 Gmail 仍能将引用内容折叠在“•••”后面。转发邮件也会带上图片。
• 附件要么字节完全一致，要么拒绝处理：使用服务器文件根目录（MCP_FILE_ROOTS）中的 path，或由脚本提供带有源文件 sha256 的 content_base64，绝不由模型手动输入。附件总大小上限为 30 MiB，这样略微超过 Gmail 25 MB 限制的邮件会收到 Gmail 自己的拒绝响应，同时也不会上传远超限制的附件。
• 附件要么完整下载，要么不提供。 系统会将每个部分的长度与 Gmail 标示的大小进行核对，且文件绝不会覆盖另一个不同文件（第二个 invoice.pdf 会变为 invoice (2).pdf）。Gmail 的“下载所有附件”压缩包会悄悄漏掉以邮件 ID 为键的部分，因此 harvest_attachments 会改为遍历每封邮件的 MIME 树。
• 读取。 正文会截断至 40,000 个字符；纯 HTML 正文会转换为文本，并注明这一点（bodySource）。Gmail 链接使用 ?authuser=<address>，因为 /u/0/ 取决于登录顺序。
• 速度。 search_threads 每次获取 16 个邮件会话的元数据，且只读取摘要所需的标头：Gmail 的批处理端点会依次执行子请求，经测试速度更慢。

日历

忙碌时间来自事件，而不是 freebusy.query，因为它不接受 calendar.events 权限范围，也无法判断暂定时段或全天事件所占的日期。日程冲突、free_busy 和 find_time 共用一条规则（calendar/domain/events.ts）：

事件	计为
已确认，或尚未回复的邀请	忙碌
标记为暂定，或回复“可能参加”	忙碌，并标记为 tentative；只有设置 tentative_is_free 时，find_time 才会将其视为可预约
已拒绝、“显示为有空”、已取消，或工作地点条目	空闲
全天且保留为忙碌	按其日历所在时区，从午夜到午夜计为忙碌
忙碌，但没有可用的开始或结束时间	列在 unknown 下，不会被丢弃

• 统一时间线。 重叠或首尾相接的时段会合并，因此同一会议出现在两个账户中也只计一次。其他人的时间（attendees）来自 freebusy.query，并会通过每个账户查询；任何人若不可见，则标记为 unknown，而非空闲。
• 时间。 2026-09-29 表示一整天；find_time 一次处理一个当地日期，因此夏令时切换前后，09:00 仍是 09:00。
• 写入。 系列 ID 看起来像某个实例的 ID，因此要对整个系列操作，需使用 scope: "series"。meet: true 会为该次写入生成请求 ID，因此重试时只会调用一次 Meet。专注时间和外出状态会根据 Google 的规则进行检查（主日历、非全天、没有访客、始终为忙碌）；除非 auto_decline 指定，否则不会拒绝任何邀请：每次拒绝都会向组织者发送邮件。

Drive

• 路径是查询条件，而非地址。 一个文件夹可以包含两个同名对象：resolve_path 会返回两个 ID，而 move_file 会拒绝创建这样的同名对象。名称可以包含 /（Meet 会创建类似 Weekly sync - 2030/01/15 的文件夹），这类对象只能通过 ID 访问。macOS 上创建的名称通常以 NFD 形式存储，因此每次查找都会同时尝试两种拼写形式。
• 移动只进行一次元数据调用。 在同步的本地副本中，文档是占位文件；将其移动到那里会使同步操作用占位文件替换文档。
• 双向校验字节。 upload_file 会将 Drive 自身的校验和（或读回的字节）与源文件进行比较，并撤销不一致的更改（替换文件时删除新版本，新建文件时移至回收站）；download_file 会在写入任何内容之前进行校验。转换格式的上传没有可供比较的字节，因此校验内容是 Drive 是否创建了所请求的 Google 文件类型。
• 速率限制。 Drive 会将速率限制作为带有原因的 403 返回，这里会将其视为速率限制，而非权限失败。配额按分钟计算，因此遇到拒绝时至少等待 22 秒（Docs、Sheets 和 Slides 也一样）。

Docs、Sheets 和 Slides

这些操作（Markdown 章节、按表头键控的行、根据大纲创建的演示文稿）通过经过测试的纯函数，处理容易出错的计算（Docs 的 UTF-16 索引、Sheets 的网格坐标、Slides 的对象 ID）。完整 API（get_*、find_in_document、batch_update_*）则提供其余功能。

• 每次写入都是一个请求：Docs 或 Slides 的 batchUpdate 会固定到计算时所依据的修订版本；Sheets 的 batchUpdate 则要么整体应用，要么完全不应用。如果请求可能已到达 Google，就绝不重试。文件可通过 ID 或 URL 指定。
• 每个批次都会在发送前进行检查，依据的是 API 的 Discovery 文档，存放在 src/<product>/domain/discovery.json（运行 npx tsx scripts/refresh-discovery.ts 刷新）：检查类型、字段、数据类型、枚举值、只读字段和字段掩码，并为拼写错误给出最接近的正确名称。所有问题会在一次拒绝中一并返回，且不会发送任何内容。 editors_api_reference 读取同一文档，因此其描述与检查器接受的内容完全一致；而仅针对 Sheets 请求的 JSON Schema 会让每个会话都加载数百 KB 的数据。
• Docs。 get_document 会显示每个元素的 [startIndex, endIndex)；非文本元素占用的每个索引都对应一个 U+FFFC。指定索引的批次必须提供 expected_revision（如果文档已更改则会被拒绝）或 target_revision（Docs 会将这些位置映射到后续编辑中）。 如果 edit_document_section 要处理的章节包含 Markdown 无法表示的内容（例如图片或脚注；read_document 会将其计为 notShown），就会拒绝操作，除非 drop_hidden 为 true。find_in_document 中的 regex 会在全新的 JavaScript 上下文中运行，时间限制为 1.5 秒，因此回溯模式无法使进程停滞。
• Sheets。 read_rows 会按照表格所在时区读取日期；货币单元格则读取为 {value, amount, formatted}，其中 amount 是精确的十进制字符串。写入时，"=..." 表示公式，"YYYY-MM-DD" 表示日期，{"amount": "12.50"} 表示数字；如果双精度数无法精确表示该值，操作就会被拒绝。
• 本地图片。 Docs 和 Slides 只能插入通过 URL 获取的图片，因此 images 中的每个 PNG、JPEG 或 GIF（名称对应文件路径）都会上传到账号的 Drive，并在本批次执行期间通过链接共享；之后会取消共享并移至回收站，无论操作结果如何。结果会说明每个副本的处理情况。
• Developer Preview 请求（评论、接受建议）会通过检查；但如果 Cloud 项目不在 Google 的预览计划中，Google 会拒绝这些请求。

Tasks、联系人和 Meet

• Tasks。 截止日期是日期：Google Tasks 会保留 UTC 午夜时间并丢弃任何具体时间。include_completed 还会显示在 Google 自有应用中已完成的任务，而 API 默认会隐藏这些任务。
• 联系人。 结果按地址合并：先是联系人，然后是目录，最后是 Gmail 保存的地址。账号无法读取的来源会列在 unavailable 下，绝不会被当作没有联系人。
• Meet。 list_meetings 会通过 Meet 代码查找日历事件对应的会议（使用账号的 Calendar 授权读取）；对于单次会议，还会查找开始时间与该事件相差不超过一小时的那场会议。转录和笔记都是 Google Docs，因此可用 read_document 打开；get_transcript 会将其读取为 [0:12:05] Ana Popescu: ...，并根据参与者为每位发言者标注姓名。

scripts/ 中的冒烟测试脚本会使用真实账号调用已构建的服务（或通过 MCP_URL 调用正在运行的服务）；会写入数据的脚本会使用 SMOKE_ACCOUNT，并在结束后自行清理。

限制

• 无法永久删除邮件或文件，只能移至 Gmail 和 Drive 的垃圾桶。不过，在此处删除的草稿、标签或过滤器会彻底消失。
• 过滤器只能设置标签（不能转发邮件），而且 Gmail 不支持更新过滤器：创建新的过滤器，再删除旧的。
• Drive 只保留一个授权，因此 Drive 工具只能访问一个账号的 Drive；其他账号的文件则通过 Docs、Sheets、Slides、评论和共享工具访问。
• 授权需要浏览器，而且必须手动复制重定向地址；没有进程监听回环端口。
• read_doc 会将 Sheet 的第一个标签页读取为 CSV（Drive 的导出功能无法选择标签页）；read_rows 可以读取任意标签页。
• Docs 的 Markdown 工具：编号列表下的项目符号会变成子编号（每个列表预设一种编号），水平分隔线会被丢弃，图片会变成链接。
• API 完全无法实现的操作：在 Docs 中插入水平分隔线或设置某一列表层级的符号、创建建议、将 API 评论锚定到 Doc 中的文本、在 Slides 中添加动画。Apps Script 可以实现其中部分操作，但需要单独的项目和授权。
• 图片通过 Google 抓取的 URL 插入 Docs 和 Slides，因此批处理期间，本地文件会通过 Drive 链接共享数秒。Sheets API 不会插入图片（=IMAGE() 公式需要一个长期公开可用的链接）。
• Sheets 不支持条件写入：如果有人在计划读取和写入之间插入行，这些行会使写入位置发生偏移，而且 API 没有修订版本锁定机制。
• 架构检查知道此服务构建时使用的 API 修订版本：如果 Google 后来添加了某个字段，检查会拒绝该字段并指出对应修订版本，直至刷新 Discovery 文档。
• Tasks 在此处无法删除；重复任务无法更改列表（Google 不允许）；截止日期没有具体时间。
• 目录只对 Workspace 账号提供查询；个人账号的查询结果会显示为 unavailable。
• Meet 将记录保留 30 天，只显示账号参与或组织的会议；只有启用了转录或智能笔记的会议才会提供这些内容（这是 Workspace 功能）。
• 大小限制：单封邮件的附件总计最多 30 MiB；Drive 上传或下载最多 100 MiB；free_busy 和 find_time 的查询范围最多为 62 天。

Google Workspace 的其他服务

搜索日期：2026-10-15。Google 运行自己的服务，另有两个覆盖范围广、由社区维护的服务：

• Google 的远程 MCP 服务，适用于 Gmail、Drive、Docs、Sheets、Slides、 Calendar、Chat、People 和 Classroom：开发者预览版，必须先将 Google Cloud 项目加入计划，通过 Streamable HTTP 使用，每个账户需要单独建立 OAuth 连接。功能较少：Gmail 服务不能发送邮件、下载附件或增量同步；Drive 服务不能移动、重命名或将文件移至垃圾桶；Docs、Sheets 和 Slides 接受未经检查的原始 batchUpdate。 docs/google-gaps.md 逐个比较了它们的工具。
• googleworkspace/cli，Google 的命令行工具，已移除 MCP 模式； 其 Gemini CLI 扩展 gemini-cli-extensions/workspace 是一个 stdio 服务，供一个已登录账户使用。
• PyPI 上的 workspace-mcp：支持 stdio，或通过 OAuth 2.1 使用 Streamable HTTP 服务多个用户；提供覆盖十二种产品的 120 多个工具，包括 Forms、 Tasks、Chat、Contacts 和 Apps Script；每次调用都以一个账户的身份执行。
• npm 上的 @aaronsb/google-workspace-mcp：支持 stdio，每个账户的 OAuth 令牌保存在本地磁盘，因此可并列使用多个账户；支持 Gmail、 Calendar、Drive、Docs、Sheets、Tasks、Meet 和 Contacts，不支持 Slides。

社区服务覆盖的产品更多。本服务的独特之处在于提供了其他服务都没有的功能：一次调用即可搜索邮件、读取所有账户的议程（包括账户间的冲突）和空闲/忙碌状态，且写入操作没有默认账户；Gmail 从 historyId 开始同步；Drive 提供更改游标和修订版本；Docs、Sheets 和 Slides 既可作为操作使用，也支持各自 API 的完整 batchUpdate，发送前会根据 API 的架构进行检查；Docs 编辑还会固定到计算该编辑所依据的修订版本。