gdocs-mcp

@dasasian/gdocs-mcp

一个 MCP 服务，让 AI Agent（例如 Claude Code）能够像操作本地文件一样操作 Google 文档——读取文档、按内容编辑、审核并处理建议、管理评论，以及在标签页和多个 Google 账号之间协作。

状态： beta。工具功能已完备，每项更改都会通过在线 API 验证，而不仅仅是运行单元测试。Markdown 代码块是目前唯一尚未支持渲染的结构（参见路线图）。

为什么要开发它

大多数 Google 文档 MCP 服务都会把文档当作纯文本处理。它填补了其他工具都没有解决的空白：

• 可直接处理的差异建议。 list_suggestions 会以 修改前 → 修改后 的形式显示待处理的修订；apply_suggestions 可以干净利落地接受或拒绝一项或多项建议。read_doc 还能将其以内嵌的 <ins>/<del> 形式呈现。
• 像文件一样编辑。 edit_doc 会匹配一段唯一的文本片段（类似本地的 Edit），并重写该片段——不会暴露索引。
• 评论。 读取讨论串（作者、引用文本、回复、解决状态），回复、解决和添加评论。
• 将标签页作为子文件。 一份文档就是一个标签页文件夹：drive ls <doc> 会列出标签页，drive mv 可以重命名、重新排序和嵌套标签页。
• 多个账号。 授权多个 Google 账号，并为每个项目选择默认账号。

你可以提出的需求

你不需要调用工具，只需用日常语言提出需求，由 Agent 来调用工具。

填充模板，无需重建文档

“将 Proposal Template 复制到 /Clients/Acme，命名为‘Acme Q3 Proposal’，然后填写客户名称、日期和定价表。”

副本会保留信头、原尺寸徽标、字体和页面设置——所有这些都是 Markdown 往返转换无法重建的。之后只需编辑发生变化的文字。否则就只能把已有文档重新输入一遍。

用一条指令完成整轮审阅

“以差异形式展示待处理的建议，接受修正错字的建议，拒绝任何会改变含义的建议，然后回复未解决的评论，并解决已经处理完的评论。”

一句话调用四种工具，而你真正需要帮助的，是中间的判断过程。大多数 Docs 集成根本看不到修订，更不用说安全地处理它们了。

**更多用途：**将一组 Markdown 文件发布为 Drive 文件树、审查多份文档的风格偏差、将文档及其图片拉回仓库 → docs/recipes.md。

安装

npm install -g @dasasian/gdocs-mcp

也可以从源代码安装：

git clone https://github.com/dasasian/gdocs-mcp && cd gdocs-mcp
npm install && npm run build
npm link   # makes `gdocs-mcp` available globally, same as the published package

然后严格按照下方说明完成设置，就像普通安装用户一样。（npm link 会将 gdocs-mcp 二进制文件符号链接到你的构建版本；开发工作流请参阅CONTRIBUTING.md。）

设置

你需要一个 Google Cloud OAuth 客户端（一次性设置）。每位用户都创建自己的客户端，这样凭据归你所有，也能避免 Google 针对受限的 Drive 范围进行应用验证。

1. 创建项目并启用 API（或使用设置指南）：

   gcloud projects create my-gdocs-mcp
   gcloud config set project my-gdocs-mcp
   gcloud services enable docs.googleapis.com drive.googleapis.com
   

2. OAuth 同意屏幕（Cloud Console → APIs & Services → OAuth consent screen）：用户类型选择 External，并将自己添加为 Test user。如需长期有效的令牌，将发布状态设为 In production（避免刷新令牌 7 天后过期）。
3. OAuth 客户端 → 创建凭据 → OAuth client ID → Desktop app。下载 JSON 并将其保存为 ~/.config/gdocs-mcp/client_secret.json。
4. 授权账号（会打开浏览器）：

   gdocs-mcp add-account
   

   对每个要使用的 Google 账号重复此操作。

配置 MCP 客户端

在项目的 .mcp.json（Claude Code）或等效文件中：

{
  "mcpServers": {
    "gdocs": {
      "command": "gdocs-mcp",
      "env": { "GDOCS_DEFAULT_ACCOUNT": "[email protected]" }
    }
  }
}

GDOCS_DEFAULT_ACCOUNT 用于设置此项目默认使用哪个已授权账号，因此工作项目和个人项目可以分别使用不同的账号，无需重新授权。任何工具调用都可以通过 account 参数覆盖此设置。

希望所有项目都能使用它？在用户范围内注册一次即可：claude mcp add gdocs -s user -e [email protected] -- gdocs-mcp。然后，项目可以通过 .gdocs-mcp.json 指定自己的默认设置——账号，以及新文档的默认 folder：

{ "account": "[email protected]", "folder": "https://drive.google.com/drive/folders/…" }

write_doc 只会根据路径创建文档（/Reports/Q3 Report）。如果给出的是不含路径的名称（Q3 Report），它不会创建任何内容：它会拒绝操作，告知 Agent 文档将放入默认文件夹，并返回完整路径供其调用。同样，如果要在“我的云端硬盘”顶层创建新文档（/Q3 Report），首次调用会被拒绝；如果你希望文档放在那里，重复相同的调用即可继续。默认文件夹的路径也会写在 write_doc 的说明中，该说明会在服务启动时读取。如果没有设置默认文件夹，系统会提示指定文件夹（~/Q3 Report）。完整的解析顺序请参阅 docs/setup.md。

你不必手动编辑该文件——只需告诉 Agent “将 [email protected] 设为此项目的默认账号” 或 “将我的 Manuscripts 文件夹设为此处的默认文件夹”，它就会通过 set_project_default 为你写入 .gdocs-mcp.json（如有需要，还会按名称搜索文件夹）。

工具

下表是参考内容。关于实际可以提出哪些请求，请参阅上文的可以提出哪些请求，或查看完整列表 docs/recipes.md。 | 工具 | 描述 | |---|---| | read_doc | 以 Markdown + 内嵌 HTML 格式读取。开头包含一个 <style> 块（将命名样式表示为 CSS：p、h1–h6、.title、.subtitle）；只有在段落样式与对应规则不同时，才会显示 style="…" — 对齐方式、间距、行高、缩进；文本颜色/大小/字体则以 <span style="…"> 返回，因此样式可见且可往返还原。模式：clean · tracked（<ins>/<del>）· accepted · rejected。segment：body（默认）/ header / footer / all — 读取正文时始终会报告页眉/页脚的内容，因此信笺抬头不会被误读为空。会被解析为标记的文档文本会标记为字面文本 — <p>4. Term</p>、5 \* 3、表示实际反斜杠的 \\；以空格或制表符开头或结尾的行会读取为 <p>⇥Indented clause</p>，写入器会保留 <p> 内的每个空格和制表符，因此读取后再写回可得到相同文档。分页符会单独占一行，读取为 <div style="page-break-after:always"></div>，写回时会作为一个分页符处理 | | edit_doc | 替换唯一的文本片段（以字符串为锚点，兼容标记；新文本支持内嵌 Markdown 和 read_doc 显示的 CSS）。相同文字但标记不同，只会进行样式编辑 — 不会删除或插入。编辑 <style> 块中的规则，会通过一次 updateNamedStyle 重新设置整个文档的样式。分页符单独占一行，因此 new_string Title page\n<div style="page-break-after:always"></div> 会将下一段放到新页面上，锚点也可以跨越分页符 | | get_page_setup / set_page_setup | 读取/设置文档级页面设置：页边距、页面大小（预设或明确指定）、方向（文件 > 页面设置） | | write_doc | 像本地 Write 一样写入：指向不存在内容的路径会创建内容 — 文件夹中的文档（/Work/Contract）、文档中的标签页（/Work/Contract/Notes）、子标签页（/Work/Contract/Part 2/Ch.4）— 且不会询问。指向已有内容的路径会替换内容；首次调用会被拒绝，并返回损失摘要：段落、评论、建议、制表位、人员/日期/链接智能标签、书签链接、分节符、分栏符，以及 confirmLoss 字符串。请告知用户；再次调用时传入该字符串即可替换。如果文档期间发生更改（该字符串包含文档版本和计数），操作会再次被拒绝。支持 Markdown 输入（与 read_doc 显示的 CSS 相同：<style> 块、<p style>、<span style>；不支持的属性会在发送任何内容前导致写入失败；分页符需单独占一行，写作 <div style="page-break-after:always"></div>，<hr style="page-break-before:always">、break-before: page 和 break-after: page 也有效，而其他任何 <div> 或 <hr> 都会被拒绝）；长文本可使用 contentFile；返回 images { src, objectId } | | insert_content | 在指定位置插入新的 Markdown 内容 — at: "end"（默认）/ "top" / 唯一锚点。适用于在文档末尾的表格后添加段落，此时 edit_doc 没有可用的锚点。支持与 write_doc 相同的分页符行 | | export_doc | 将文档导出到本地文件 — pdf（默认）、docx、odt、rtf、txt、html、epub、md（由 Google 在服务端渲染）。文档路径会导出所有标签页；标签页路径（/Work/Contract/Ch.4）只会导出该标签页（不包括其子标签页），使用的是未公开且有速率限制的 Google 端点；如果失败，则会拒绝操作，而不会扩大导出范围 | | list_suggestions | 以 before → after 差异形式列出待处理的建议 — 可用 segment 读取页眉/页脚中的建议 | | apply_suggestions | 原子性地接受或拒绝一个或多个建议 — 处理重叠/相邻的“簇”时必须使用；可用 segment 处理页眉/页脚中的建议 | | insert_image | 从 URL 或本地文件插入内嵌图片 — 可设置位置、大小、左/居中/右对齐。segment: "header"（+ createSegment）可将信笺抬头徽标放到重复显示的位置 | | download_images | 将文档中嵌入的图片下载到本地文件夹（与 read_doc 的图片标记配合使用 — 即发布的逆向操作） | | insert_table | 插入 rows×columns 表格 — 填充数据（单元格支持内嵌 Markdown）、逐列设置 align、列宽、表头底色；可用 segment/createSegment 插入信笺抬头表格 | | edit_table | 表格结构操作 — 插入/删除行或列（精准操作 — 通过单元格文本定位表格）；可用 segment 操作页眉/页脚表格 | | set_table_style | 设置现有表格的样式（通过单元格文本定位）：单元格内边距、背景色、单元格边框（width: 0 = 无边框）、列宽、固定表头行 — 作用范围可选表格/行/列/单元格；可用 segment 操作页眉/页脚表格 | | get_table_style | 读取表格样式（通过单元格文本定位）：列宽、固定表头行，以及匹配单元格的内边距、背景色和各边框 — 对应 set_table_style 的读取操作 | | list_comments / add_comment / resolve_comment | 评论讨论串（add_comment 也可通过 replyTo 回复） | | drive | 将 Drive 用作文件系统：ls find mkdir cp mv。路径为 / 或 ~（我的云端硬盘）、/shared/<drive>、/shared-with-me、/lost+found；其他路径均视为 ID。cp 会保留 Markdown 无法往返还原的内容（页眉/页脚、图片尺寸、精确格式），因此优先使用它，而不是重新构建模板。参见 将 Drive 用作文件系统。文档是由其标签页组成的文件夹：ls <doc> 会列出标签页，ls <folder> 会显示每个文档的标签页数量，路径可继续进入标签页（/Work/Contract/Part 2/Ch.4），而 mv 可重命名、嵌套（dst 是另一个标签页）、取消嵌套（dst 是文档），并可通过 index 对标签页重新排序（mv <doc>/Summary <doc>/Summary 配合 index: 0 可原地重新排序）。标签页不能移出其所属文档，复制标签页的 cp 操作会被拒绝 | | list_permissions / share_doc / unshare_doc | 共享（share_doc 同时支持共享给个人和任何持有链接的人）。list_permissions 会列出所有受众，包括 Workspace 在创建时添加的全域授权；unshare_doc 可通过 permissionId 撤销这些授权，并且需要 expectRole，因为撤销操作不会出现在任何版本历史记录中 | | list_accounts | 已授权的 Google 账号 | | set_project_default / get_project_config | 设置/显示此项目的默认账号和文件夹（写入 .gdocs-mcp.json） | 每个文档工具都接受一个用于指定文档的 path——可以是 ID、URL、/Work/Contract 或 /Work/Contract/Ch.4——以及一个可选的 account（用于覆盖默认值）。只有一个标签页的文档无需指定标签页；有多个标签页的文档在指定其中一个之前会被拒绝，拒绝信息会列出每个标签页的路径。两个同名标签页（或文件夹和文档）会被拒绝，并列出每个候选项的 ID。

将 Drive 当作文件系统

Drive 导航由一个使用 shell 语法的工具负责，因为模型已经熟悉 shell。参数按位置传入，并且因命令而异，与终端中的用法完全相同。

{ "cmd": "ls",    "args": ["/Work/2026"] }
{ "cmd": "find",  "args": ["quarterly report", "-type", "d"] }
{ "cmd": "mkdir", "args": ["-p", "/Work/2027/Q1"] }
{ "cmd": "cp",    "args": ["/Work/Template", "/Work/2027/Q1/Report"] }
{ "cmd": "mv",    "args": ["/Work/Roof", "/Archive"], "expectName": "Roof" }

路径	表示
/… 或 ~/…	我的云端硬盘
/shared/<drive name>/…	共享云端硬盘
/shared-with-me	他人与你共享、且你从未归档的文件
/lost+found	你拥有但不在任何文件夹中的文件——见下文
其他任何内容	Drive ID 或 URL，因此可直接粘贴来自任何其他工具的 ID

标志和操作数可按任意顺序解析（cp -r a b、cp a b -r、cp a -r b），而 -- 用于结束选项。

Drive 有三处与文件系统不同。 仅在恰当之处借用文件系统术语，不适用之处则会拒绝操作：

• 同一文件夹中可以有两个同名文件，且匹配时不区分大小写。模型学过的文件系统都没有这两种情况，所以它不会想到要检查。路径匹配到多个对象时会拒绝操作并列出候选项，绝不猜测——cp/mv 也会拒绝创建这种状态，而不会制造出解析器随后无法判定的歧义。
• cp -r 不可用。 Drive 的 files.copy 会拒绝复制文件夹（Drive 自己的网页界面也无法复制文件夹），因此对文件夹执行 cp 时会说明原因，而不会只完成一半。
• 将文件 mv 到 /shared/… 会转移文件所有权。 shell 的 mv 跨文件系统移动文件时，文件所有权仍归你；而移入共享云端硬盘会将所有权转给该组织，你无法自行撤销。此操作需要 acceptOwnershipTransfer: true。

路径所能看到的内容少于 find。 没有父级文件夹的文件仍可打开，也仍会出现在搜索结果中，但无法通过路径指定——任何浏览目录树的方式都不会显示它。find 会显示完整内容；这些文件会出现在 /lost+found 中。

没有 rm。参见 #47。

已知限制

这些是 Google API 的限制，而非 bug——以下列出了重点；完整参考（含 API 原因和各项限制的解决方法）见 docs/limitations.md。

• 无法 创建 建议。 API 不支持在建议模式下写入——所有编辑都会直接应用（即时修改文本）。apply_suggestions 只能处理现有建议。会写入内容的工具都会明确说明。
• 没有建议归属信息（作者/时间戳）——建议按文档中的顺序列出。
• 通过 API 创建的评论不会锚定到文本，且 Drive 只会返回作者的姓名（不含电子邮件）。
• 图片只能内嵌（不支持浮动及 x、y 定位），且 Google 会缩小并重新编码嵌入的图片，因此拉取的副本与原文件的字节并不完全相同。
• 页眉和页脚是独立的内容树——不属于正文。每个内容工具（read_doc、edit_doc、insert_content、insert_image、insert_table、edit_table、set_table_style、list_suggestions、apply_suggestions）都接受 segment: "header" | "footer" 来访问页眉或页脚；如果文档定义了多个页眉或页脚，还需传入 page。
• 样式通过 markdown 内的 CSS 设置——read_doc 会以包含命名样式的 <style> 块开头，并在段落或文本片段与对应规则不同时显示 style="…"；edit_doc 可以修改样式（文本相同但标记不同的编辑仅修改样式），写入工具也接受相同的 CSS。支持的属性有限（text-align、line-height、margin-*、text-indent、font-*、text-decoration、color，单位为 pt）；其他属性会在发送请求前被拒绝。复杂的表格样式由 set_table_style 处理。markdown 暂不支持渲染代码块（已列入路线图）。

完整表格及各项限制的缓解或呈现方式，请参阅 docs/limitations.md。

路线图

• markdown 写入器支持代码块——这是剩余的 Tier-2 块类型（表格和图片已支持渲染；也提供独立的 insert_table / insert_image 工具）。

建议归属信息（作者/时间戳）不在路线图中——对于典型建议，API 不提供相应途径（见 docs/limitations.md）。

“手稿同步”用例（章节文件 ⇄ 标签页、审阅建议、合并）有意不作为服务功能——由 AI Agent 基于这些原语进行编排。见 DESIGN.md §10b。

开发

npm install
npm run build      # tsc
npm test           # vitest
npm run typecheck

完整架构及其背后的实证发现，请参阅 DESIGN.md。

致谢

本项目的架构和方法参考了此前开源的 Google Docs MCP 服务，尤其是 @a-bonus/google-docs-mcp 和 taylorwilsdon/google_workspace_mcp。

许可证

MIT © Dasasian